# Kimai

Self-hosted team time tracking with invoicing and a Builder-documented JSON API.

Kimai is a multi-user time-tracking web application for freelancers and companies: timesheets, customers, projects, activities, budgets, invoicing, exports and a plugin store. The Builder publishes a bearer-token REST API with an OpenAPI export, and sells a hosted edition at kimai.cloud. Self-hosting is configured through .env and config/packages/local.yaml.

Alternative to: Toggl Track, Harvest, Clockify

- Capabilities: adaptable, operable
- Vertical: scheduling-staffing
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/kimai/kimai (AGPL-3.0), 4954 stars, last commit 2026-08-31
- Last activity: 2026-08-31
- Page: apps/kimai--kimai.html
- JSON: apps/kimai--kimai.json

## Use it when

- my team bills by the hour and I want timesheets, rates and invoices in one place I run myself
- I want my agent to log time and pull project hours through an API instead of a spreadsheet

## Gotchas

- AGPL-3.0: modifications to a hosted instance must be shared with its users; some Adopters cannot accept this
- Must run on a subdomain; installing in a subdirectory is not supported
- API tokens are shown once at creation; API attribute order is not stable and DateTime values must use YYYY-MM-DDTHH:mm:ss, not ISO 8601
- Leave management, overtime and expenses are paid plugins or Cloud Professional features, not core

## Editions

- Self-hosted: Free, open source
  - source: https://github.com/kimai/kimai
  - container: https://hub.docker.com/r/kimai/kimai2
- Kimai Cloud Standard: €4 per user/month, closed source
  - hosted: https://www.kimai.cloud/
- Kimai Cloud Professional: €5 per user/month, closed source
  - hosted: https://www.kimai.cloud/

## Adaptable: make it yours

Effort: config-only (6 things to edit)

Deploy with Docker or Composer, set DATABASE_URL, MAILER_URL and MAILER_FROM in .env, then put shop rules in config/packages/local.yaml: multiple time-rounding rules (per weekday), weekday rate multipliers, permission sets and role maps, active-entry limits, invoice template search paths, and LDAP or SAML login. Time-tracking mode, lockdown periods, invoice number formats, branding, rates, budgets, customers and projects are set in the UI under System > Settings.

- Env vars: DATABASE_URL, MAILER_URL, APP_ENV, MAILER_FROM
- Config files: .env, config/packages/local.yaml
- Prompt files: none
- Accounts you'll need: Kimai Cloud (hosted edition only)

## Operable: what an agent can drive

Operability: official. Interface: api at https://www.kimai.org/documentation/rest-api.html (published by the builder, both).

### Reach (partial coverage)

- Record and edit timesheets: reachable. rest-api.html lists timesheets as an API resource; OpenAPI export at /api/doc
- Manage customers, projects and activities: reachable. rest-api.html lists customers, projects and activities resources
- Manage users: reachable. rest-api.html lists users as an API resource
- Manage teams and permissions: undetermined. not named on the REST API page; check the /api/doc export on a running instance
- Create invoices: undetermined. rest-api.html does not say whether invoices can be created through API
- Run reports and exports: undetermined. reports and exports are UI features; no report endpoint named in the REST docs
- Configure timesheet rules, rounding and lockdown: not reachable. these live in config/packages/local.yaml, not the API
- Install plugins from the store: not reachable. plugins are installed on the server filesystem; no API
- Authenticate with SAML or LDAP: not reachable. configured in local.yaml; not an API job

## Code stack

- Languages: PHP, JavaScript
- Frameworks: Symfony, Doctrine, Tabler, Bootstrap
- Package manager: composer
- Database: MariaDB, MySQL
- Hosting target: docker, on-premise, hetzner, digitalocean, synology

## Evidence and confidence

- formFactor: README: web-based multi-user application, PHP 8.2+, MariaDB/MySQL (confidence 0.95)
- executionModel: no model SDK or AI feature in README or config docs (confidence 0.95)
- operability: kimai.org/documentation/rest-api.html published by the Kimai project; bearer token; OpenAPI export at /api/doc (confidence 0.9)
- effort: kimai.org/documentation/configurations.html names config/packages/local.yaml and .env keys DATABASE_URL, MAILER_URL, APP_ENV (confidence 0.8)
- editions: README links kimai.cloud; kimai.cloud lists Standard EUR 3.99 and Professional EUR 4.99 per user per month with a 30-day trial (confidence 0.85)
- active: shortlist pushedAt 2026-08-31; README says releases every couple of weeks
- reach:  (confidence 0.7)

## Open questions

- Does the REST API expose invoice creation and team management? Export /api/doc from a running instance to settle Reach
- Is the API available on Kimai Cloud plans without restriction?
- glazperle/kimai_mcp (34 stars, pushed 2026-08-14) exists as a third-party MCP wrapper; note it as a convenience, not the basis of operability

## Sources

- https://github.com/kimai/kimai (sourcing:scheduling-staffing:curated)
- https://www.kimai.org/documentation/rest-api.html (sourcing:scheduling-staffing:curated)
- https://www.kimai.org/documentation/configurations.html (analysis:scheduling-staffing)
- https://www.kimai.cloud/ (analysis:scheduling-staffing)