Kimai: Self-Hosted Time Tracking for Freelancers and Teams

Productivity 2026-03-04 · 3 min read kimai time tracking freelance self-hosted docker invoicing project management open-source
By Selfhosted Guides Editorial Team — Self-hosting practitioners covering open source software, home lab infrastructure, and data sovereignty.

Cloud time trackers lock your billing data in proprietary systems with subscription fees. Kimai is the self-hosted alternative: track time by project and activity, generate invoices, manage multiple users, and keep all data on your own server. It's been actively maintained since 2006 and is particularly well-suited to freelancers and small agencies.

Photo by Chris Stein on Unsplash

What Kimai Does

Time tracking: Start/stop timers, manual entry, bulk import
Projects and activities: Organize time by client → project → activity
Invoicing: Generate invoices from tracked time with customizable templates
Reports: Export by project, client, user, or date range
Team features: Multi-user, role-based access, team timesheets
API: REST API for integration with accounting software
Mobile: PWA for time entry on mobile

Docker Setup

services:
  kimai:
    image: kimai/kimai2:apache
    container_name: kimai
    restart: unless-stopped
    ports:
      - 8001:8001
    volumes:
      - kimai_data:/opt/kimai/var/data
      - kimai_plugins:/opt/kimai/var/plugins
    environment:
      DATABASE_URL: mysql://kimai:kimai_db_password@kimai-db/kimai
      APP_SECRET: change-this-to-random-string
      TRUSTED_PROXIES: nginx,localhost,127.0.0.1
      TRUSTED_HOSTS: kimai.yourdomain.com,localhost
      MAILER_FROM: [email protected]
      MAILER_URL: null://null

  kimai-db:
    image: mysql:8.0
    container_name: kimai-db
    restart: unless-stopped
    volumes:
      - kimai_db:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: kimai
      MYSQL_USER: kimai
      MYSQL_PASSWORD: kimai_db_password

volumes:
  kimai_data:
  kimai_plugins:
  kimai_db:

Navigate to http://your-server:8001. Create the first admin user:

docker exec -it kimai bin/console kimai:user:create admin [email protected] ROLE_SUPER_ADMIN

Core Concepts

Customers: Clients you do work for. Each customer can have multiple projects.

Projects: Billable units within a customer. Set hourly rates at the project level.

Activities: Types of work within a project (Development, Design, Meetings, Research). Activities can have their own rates.

Timesheets: Individual time entries — who did what, for which project/activity, for how long.

Tracking Time

Timer: Click "Start" → select customer/project/activity → click "Stop" when done.

Manual entry: Add a timesheet entry with start/end time directly.

Bulk import: Import CSV timesheets for historical data migration.

Quick entry: Browser extension or mobile PWA allows one-click time start without opening the full interface.

Billing Rates

Set rates at multiple levels (highest specificity wins):

Global hourly rate: Default for all work
Customer rate: Per-client rate
Project rate: Per-project rate
Activity rate: Per-activity rate
User rate: Individual user billing rate

This flexibility handles complex billing: a client who gets a lower rate, specific activities that bill at a premium, or contractors who have different rates than employees.

Invoicing

Generate invoices directly from tracked time:

Billing → Invoices → Create
Select customer, date range, and which timesheets to include
Choose an invoice template (Kimai includes basic templates; custom templates via Twig)
Export as PDF

Invoice numbers auto-increment. You can track invoice status (draft, sent, paid).

Custom templates: Create Twig-based templates to match your brand. Place in var/invoices/.

Reports

Built-in reports:

Export: Download timesheets as CSV, Excel, PDF
User report: Hours per user over time period
Project report: Hours and cost per project
Customer report: Totals per client

All reports filter by date range, user, project, customer, and activity.

Multi-User Configuration

Add team members:

Admin panel → Users → Create
Set roles: Admin, Team Lead, User
Assign to teams and projects

Project visibility: Projects can be restricted to specific teams. Users only see timesheets and projects they have access to.

Billable vs non-billable: Mark activities as billable or non-billable. Reports can filter accordingly.

Plugins

Kimai supports plugins for extended functionality:

AuditTrail: Change logging
CustomFields: Add custom fields to customers, projects, activities
ImportBundle: Enhanced CSV import
ExpenseBundle: Track expenses alongside time

Install plugins:

docker exec -it kimai bin/console kimai:bundle:install
docker exec -it kimai bin/console cache:clear

API Integration

The REST API enables integration with invoicing or accounting tools:

# Get all timesheets for a user
curl -u "user:password" \
  "https://kimai.yourdomain.com/api/timesheets?user=1&full=true"

# Create a timesheet entry
curl -u "user:password" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"project":1,"activity":2,"begin":"2026-03-04T09:00:00","end":"2026-03-04T12:00:00","description":"Client meeting"}' \
  "https://kimai.yourdomain.com/api/timesheets"

Backup

# Backup database
docker exec kimai-db mysqldump -u kimai -p kimai > kimai-$(date +%Y%m%d).sql

# Backup data volume (uploaded files, custom templates)
docker run --rm -v kimai_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/kimai-data-$(date +%Y%m%d).tar.gz /data

Use Cases

Freelancer: Track time per client and project, generate PDF invoices from tracked hours, maintain per-client billing records.

Agency: Multi-user time tracking, team-level reporting, project profitability analysis (compare billed hours to estimated budget).

Internal cost tracking: Track time by department or cost center even for non-billable internal work.

Kimai vs Alternatives

	Kimai	Clockify	Toggl
Self-hosted	Yes	No	No
Free	Yes (self-hosted)	Free tier	Free tier
Invoicing	Built-in	Paid feature	Paid feature
API	Yes	Yes	Yes
Multi-user	Yes	Yes	Yes

The self-hosted advantage: billing data stays local, no subscription cost, full control over customization.

The project is at github.com/kimai/kimai. For freelancers tired of paying for SaaS time trackers or concerned about billing data in the cloud, Kimai is a mature, full-featured alternative.