Set Up Wakapi as a Self-Hosted Coding Time Tracker

Why Track Your Coding Time Yourself

WakaTime has long been the go-to service for tracking how developers spend their time across editors, languages, and projects. But it sends your data to a third-party server, and the free tier comes with a 14-day history limit. Wakapi is an open-source, self-hosted alternative that speaks WakaTime’s own API language – meaning your existing editor plugins work without modification, and your data stays on your own machine.

What Wakapi Is and How It Works

Wakapi is a lightweight Go application that mimics the WakaTime API endpoint. When you install a WakaTime-compatible plugin in VS Code, Neovim, JetBrains, or any of the dozens of supported editors, the plugin sends heartbeat data to whatever API URL you point it at. Normally that URL is wakatime.com. With Wakapi, you redirect it to your own server, and Wakapi handles ingesting, storing, and displaying that data through its own web dashboard.

The heartbeat model is worth understanding before you set anything up. Every time you save a file or switch focus, your editor plugin fires a small JSON payload containing the filename, project name, language, and a timestamp. Wakapi collects these heartbeats and aggregates them into sessions, durations, and daily totals. Nothing runs continuously on your machine – the plugin just sends short bursts of data at regular intervals, making the system surprisingly low-overhead for what it tracks.

Storage is handled by a SQLite database by default, which is fine for personal use. If you plan to run Wakapi for a team or want more query flexibility, it also supports MySQL and PostgreSQL. The web dashboard gives you a breakdown by project, language, editor, and operating system, with charts that mirror what WakaTime users are used to seeing. You can also expose a public profile page or keep everything private behind a login.

Wakapi also supports the Wakatime-compatible API well enough that third-party tools designed to pull from WakaTime – like certain dashboard widgets or status-bar integrations – will work against your Wakapi instance without any special configuration. That compatibility layer is what makes switching practical rather than theoretical. If you are already running a self-hosted deployment platform like Coolify, Wakapi is a natural candidate to add to your stack.

Setting Up Wakapi with Docker

Docker is the fastest path to a working Wakapi instance. Start by creating a directory for your Wakapi configuration, then pull the official image from ghcr.io/muety/wakapi. Before running the container, you need a configuration file. Wakapi reads from a wakapi.yml file, and the project’s GitHub repository includes a sample you can copy and modify. The most important fields to set are db_path for your SQLite file, password_salt (generate a random string and keep it private), and listen_port, which defaults to 3000.

A basic Docker run command looks like this: docker run -d --name wakapi -p 3000:3000 -v $(pwd)/wakapi.yml:/app/config.yml -v $(pwd)/wakapi.db:/app/wakapi.db ghcr.io/muety/wakapi:latest. The two volume mounts are what matter here – one for the config file, one for the SQLite database. Without those mounts, your data disappears every time the container restarts. If you prefer Docker Compose, the official documentation includes a ready-to-paste docker-compose.yml example that adds a restart policy and makes environment variable management cleaner.

Once the container is running, open your browser at http://localhost:3000 and you will see the Wakapi login screen. Create an account through the registration page – by default, registration is open, but you can disable it in the config file once you have created your user. After logging in, navigate to the API Keys section of your profile. Copy the key shown there; you will need it when configuring your editor plugins.

In your editor plugin settings, there are two fields to change. First, set the API URL to point at your Wakapi instance instead of wakatime.com. For a local setup that would be http://localhost:3000/api, or your server’s domain if you are hosting remotely. Second, paste in the API key you copied. In VS Code, these settings live inside the WakaTime extension preferences under wakatime.apiUrl and the standard API key field. In Neovim with the vim-wakatime plugin, you edit the ~/.wakatime.cfg file directly, adding api_url = http://your-server:3000/api alongside your key.

Give it a few minutes of coding and then reload the Wakapi dashboard. You should see your first heartbeats appearing in the activity feed and your first language tallying up time. If nothing shows up, check the container logs with docker logs wakapi – the most common issue is a misconfigured API URL in the plugin, often a missing trailing slash or a wrong port. Wakapi logs incoming heartbeats verbosely at the debug level, so turning that on in your config temporarily makes diagnosis much faster.

Putting Wakapi Behind a Reverse Proxy

Running Wakapi on localhost is fine for testing, but for daily use you will want it accessible over HTTPS on a proper domain. Nginx and Caddy are both well-suited for this. With Caddy, the configuration is minimal – point your domain at the server, add a reverse_proxy localhost:3000 directive, and Caddy handles certificate provisioning automatically through Let’s Encrypt. With Nginx, you need to add a proxy_pass block and handle your SSL certificate separately using Certbot. Either way, once HTTPS is in place, update the API URL in your editor plugin to use the secure domain.

One setting worth adjusting after you go live is the max_inactive_seconds value in the config file. Wakapi uses this to decide when a gap between heartbeats counts as the end of a session. The default is 1800 seconds – thirty minutes. If you frequently step away from your editor mid-task, you may find your session totals chopped into fragments. Increasing it to 3600 or even 7200 gives a more realistic picture of focused work sessions, though it also means distractions get folded into your tracked time rather than excluded from it.