Wakapi

Wakapi is a minimalist, self-hosted backend for coding statistics that is fully compatible with the WakaTime heartbeat API. Developers can point any WakaTime-compatible IDE plugin at their own Wakapi instance and immediately begin collecting detailed breakdowns of time spent by project, language, editor, operating system, and host — without ever sending data to a third-party cloud.

Built in Go and compiled to a single static binary, Wakapi is designed for simplicity of deployment. It ships with SQLite out of the box, supports MySQL and PostgreSQL for larger deployments, and runs in Docker, Docker Compose, or Kubernetes via a community Helm chart. A hosted cloud version at wakapi.dev is also available for users who want the experience without the operational overhead.

Beyond raw data collection, Wakapi generates weekly email reports, maintains a configurable public leaderboard, exposes a Prometheus metrics endpoint for monitoring integration, and produces Shields.io-compatible SVG badges for README files. An import tool allows migrating historical data from WakaTime, and a relay feature lets users forward heartbeats to WakaTime in parallel so both systems stay synchronized.

Authentication is multi-modal: traditional credentials with argon2id password hashing, OIDC single sign-on via external providers, WebAuthn passkey support, and multiple API keys per user for fine-grained access control. An optional Stripe-based subscription model can be enabled to fund development and unlock unlimited data retention for paying users.

What You Get

• WakaTime-compatible heartbeat API - Every WakaTime IDE plugin works without modification; just point api_url to your Wakapi instance and set your API key.
• Detailed coding dashboards - Visualize time spent by project, language, editor, branch, entity, operating system, and machine — filterable by any custom date range.
• Weekly email reports - Automated summaries delivered on a configurable schedule showing coding trends across languages and projects.
• Public leaderboard - Opt-in ranked display of coding activity across all instance users, with configurable time scopes and regeneration schedules.
• Prometheus metrics endpoint - Expose server health, request rates, active users, and heartbeat counts for scraping by Prometheus or compatible monitoring stacks.
• Shields.io badge generation - Generate embeddable SVG badges showing total coding time, top language, or most active project, compatible with any README or status page.
• WakaTime data import - Migrate historical heartbeat data from WakaTime with configurable batch sizes, rate limits, and per-host whitelisting.
• Heartbeat relay - Forward incoming heartbeats to WakaTime or another Wakapi instance in parallel to keep multiple systems synchronized.
• Multi-modal authentication - Support for password login with argon2id hashing, OIDC SSO (Google, GitHub, Keycloak, etc.), WebAuthn passkeys, and multiple API keys per user.
• Flexible data retention - Configure retention period in months or keep all data forever; an optional Stripe-based subscription can exempt paying users from retention limits.

Common Use Cases

• Personal productivity tracking with full data ownership - A developer runs Wakapi on a home server or VPS to accumulate years of coding history without WakaTime’s 14-day free tier limitation.
• Small team coding analytics - An engineering lead deploys Wakapi for their team with OIDC SSO via their existing identity provider, then pulls the REST API to build a custom Grafana dashboard showing per-engineer contribution trends.
• Open-source project contribution tracking - A maintainer embeds a Wakapi badge in their README showing total time invested in the project, updated automatically by the badge endpoint.
• Development environment monitoring - A DevOps team pairs Wakapi’s Prometheus endpoint with Grafana alerts to detect when coding activity drops unexpectedly, signaling potential blockers.
• Educational coding behavior research - A university department deploys Wakapi for students across a semester, then uses the REST API to analyze language adoption curves and editor preferences across cohorts.

Under The Hood

Architecture Wakapi follows a disciplined layered Go architecture with repositories, services, and route handlers occupying distinct roles and communicating only through explicit interfaces. Dependency injection is manual constructor-based wiring in main.go, which makes the dependency graph transparent and enables full interface substitution in tests without reflection magic. An event bus decouples cross-cutting concerns — leaderboard invalidation reacts to user update events via a pub-sub subscription rather than direct service-to-service calls. The chi router organizes HTTP concerns into separate API and MVC sub-routers with middleware stacks for authentication, security headers, logging, and Sentry error capture. Static assets and Swagger documentation are embedded directly into the compiled binary using Go’s embed directive, eliminating runtime file system dependencies.

Tech Stack The backend is written in Go 1.26 and compiled without CGO to a fully static binary suited for distroless container images. chi handles HTTP routing; GORM provides database access with drivers for SQLite (via the pure-Go glebarez driver), MySQL, and PostgreSQL. The frontend uses Go HTML templates rendered server-side, styled with Tailwind CSS 3.x and a small JavaScript layer compressed with Brotli and pre-embedded into the binary. Background scheduling runs via robfig/cron with a worker pool abstraction. Authentication integrates coreos/go-oidc for OIDC flows, go-webauthn for passkeys, and argon2id for password hashing. Optional Stripe integration powers a self-funded subscription tier for data retention benefits.

Code Quality The codebase has extensive test coverage spanning models, services, routes, config, middlewares, and utilities, all using testify suites with a dedicated mocks directory for clean dependency substitution. Error handling is explicit throughout: every database call, HTTP request, and background job surfaces errors to callers rather than swallowing them, and HTTP handlers return typed status codes with meaningful responses. SonarCloud static analysis is integrated into CI via sonar-project.properties. Naming conventions are consistent and idiomatic Go; interface definitions are small and focused. The overall signal is a codebase that takes quality seriously, with patterns that scale well as the contributor base grows.

What Makes It Unique The defining technical achievement is complete WakaTime API compatibility — the compat layer faithfully implements every WakaTime v1 endpoint that IDE plugins call, so migrating an entire development team requires only an api_url change with zero plugin reconfiguration. Beyond compatibility, Wakapi’s relay feature lets users run WakaTime and Wakapi in parallel, forwarding heartbeats to both systems simultaneously. Native Shields.io badge generation, built-in Prometheus export, multi-API-key support per user, and WebAuthn passkey authentication are all capabilities that competing self-hosted alternatives lack or delegate to third-party services. The optional Stripe-based subscription model embedded directly into a self-hosted application is an unusual pattern that lets the project sustain ongoing development without requiring a separate SaaS billing infrastructure.

Self-Hosting

Wakapi is released under the MIT License, which is one of the most permissive open-source licenses available. You are free to use it commercially, modify the source, redistribute it, and incorporate it into proprietary systems without any copyleft obligations. The only requirement is to preserve the copyright notice. There are no enterprise tiers, license keys, or source-available restrictions — the entire codebase is identical regardless of how you deploy it.

Running Wakapi yourself is operationally straightforward compared to most self-hosted software. A single compiled binary with no external runtime dependencies can serve modest workloads on minimal hardware; the default SQLite backend works well for individual developers or small teams. Larger deployments should migrate to PostgreSQL or MySQL and tune the database connection pool size via configuration. You are responsible for backup of the database file or database server, uptime, TLS termination (Wakapi exposes plain HTTP and expects a reverse proxy such as Caddy or nginx to handle TLS), and applying updates when new releases are published. The Docker image and compose.yml make upgrades straightforward, but migration of the SQLite data directory file permissions became a breaking change in recent releases — release notes should be reviewed before upgrading.

Compared to the hosted wakapi.dev cloud service, self-hosting gives you unlimited data retention at no cost, full control over authentication configuration (including OIDC and WebAuthn), and no dependency on a third-party SLA. The cloud service adds managed uptime, automatic upgrades, and removes operational burden entirely. Self-hosters who enable data retention limits can configure the Stripe subscription module to replicate the cloud service’s paid retention model, effectively running their own micro-SaaS. There is no official commercial support or enterprise SLA; community support is available via GitHub Issues, and the project wiki covers advanced setup scenarios.