Kimai: The Time-Tracking Powerhouse Every Developer Needs

Stop bleeding billable hours. Every freelancer, agency, and development team knows the pain: scattered spreadsheets, forgotten timers, and invoice headaches that devour your profit margins. What if you could track every second, generate polished invoices, and manage teams—all from a single, self-hosted dashboard? Meet Kimai, the open-source time-tracking revolution that's transforming how developers handle project management. This isn't just another timer app; it's a professional-grade, API-driven powerhouse built on modern PHP and Symfony. In this deep dive, you'll discover why thousands of developers are ditching SaaS subscriptions for Kimai's freedom, explore real code examples, and get a complete setup guide that has you running in under 15 minutes. Ready to reclaim your time and your data? Let's go.

What Is Kimai? The Open-Source Time Tracker Taking Over Development Teams

Kimai is the world's leading open-source time-tracking application, built specifically for the complexities of modern development workflows. Born from the need to track project times accurately without vendor lock-in, Kimai has evolved into a sophisticated web-based multi-user system that serves freelancers, startups, and enterprise organizations with hundreds of users.

Originally created by Kevin Papst and now powered by a vibrant community, Kimai v2 represents a complete rewrite on the Symfony framework, delivering enterprise features without enterprise price tags. The application runs on PHP 8.1+ and leverages Doctrine for robust database operations, Bootstrap/Tabler for a sleek responsive interface, and a plugin architecture that makes extensibility a first-class citizen.

What makes Kimai genuinely revolutionary is its commitment to data sovereignty. While competitors trap your valuable time data in proprietary clouds, Kimai gives you complete control—host it on your own server, integrate it with your existing tools, and customize it to your exact workflow. The JSON API enables seamless integrations with CI/CD pipelines, project management tools, and custom dashboards. With over 30 language translations, SAML/LDAP authentication, and two-factor authentication, Kimai scales from solo developers to global teams without breaking a sweat.

The project is actively maintained with bi-weekly releases, a public roadmap on GitHub Projects, and a thriving marketplace of free and premium plugins. Whether you're billing clients by the hour or tracking internal sprint progress, Kimai delivers professional-grade features that rival commercial alternatives costing thousands per year.

Key Features That Make Kimai Unstoppable

Multi-Timer & Punch-In/Punch-Out Mode: Unlike simplistic single-timer apps, Kimai lets you run multiple timers simultaneously—perfect for developers juggling maintenance and new development. Switch contexts instantly without losing a second of billable time. The punch-in/punch-out mode provides traditional time-clock functionality for teams that need rigid tracking.

Advanced Invoicing Engine: Generate PDF invoices directly from tracked time with customizable templates. Support for user-specific rates, project-based pricing, and customer-specific currencies means you never manually calculate billing again. The system handles time budgets and money budgets with visual progress indicators, alerting you before projects go over budget.

Bulletproof Authentication & Security: Kimai doesn't compromise on security. Authenticate via SAML, LDAP, or local database with role-based permissions that granularly control who sees what. Every account can be secured with TOTP-based 2FA, and the system logs all activities for compliance auditing.

JSON API & Plugin Architecture: The RESTful JSON API exposes every function, enabling integrations with Slack, Discord, Jira, or custom CI/CD pipelines. The plugin system, built on Symfony bundles, lets developers extend functionality without forking core code. The official marketplace offers everything from custom themes to advanced reporting.

Multi-Dimensional Reporting: Slice your data by customer, project, activity, user, team, or time period. Export to CSV, Excel, PDF, or JSON. The advanced filtering system handles complex queries like "show me all billable hours for Project X in Q2 by developer Y" in seconds.

Global-Ready Architecture: With multi-timezone support, automatic DST handling, and 30+ languages managed through Weblate, Kimai works seamlessly for distributed teams. The responsive design ensures perfect functionality on mobile devices, tablets, and desktops.

Real-World Use Cases: Where Kimai Dominates

The Freelance Full-Stack Developer: Sarah codes for three clients simultaneously. She sets up project-specific rates—$120/hr for React work, $100/hr for Node.js maintenance. With Kimai's multi-timer, she switches between client projects with one click. At month-end, she generates three branded PDF invoices directly from her tracked time, complete with detailed activity breakdowns. Result: Invoice creation time dropped from 3 hours to 15 minutes, and her billable accuracy increased by 12%.

The Agile Development Agency: A 15-person agency tracks sprint progress across 8 active projects. They use team permissions so project managers see only their projects. The JSON API automatically pulls time data into their custom dashboard, showing real-time burndown charts. Budget alerts notify them when projects hit 80% of allocated hours. Result: Project overruns decreased by 40%, and client transparency improved dramatically.

The Remote-First SaaS Startup: With developers in 6 timezones, they needed LDAP integration with their existing Active Directory. Kimai's SAML support enabled single sign-on, while timezone-aware logging ensures accurate tracking across continents. The punch-in/punch-out mode provides accountability for support staff. Result: Unified time tracking across all tools, zero vendor lock-in, and $5,000/year saved compared to Harvest.

The Non-Profit Organization: Tracking volunteer hours for grant reporting was a nightmare. Kimai's free self-hosted tier lets them track unlimited volunteers across programs. Custom activity types distinguish between direct service, training, and administrative work. Result: Generated grant reports in minutes instead of days, securing $200K in additional funding through accurate impact metrics.

Step-by-Step Installation & Setup Guide

Method 1: Docker Compose (Fastest & Recommended)

Get running in under 5 minutes with Docker:

# Create project directory
mkdir kimai && cd kimai

# Download the official docker-compose.yml
curl -o docker-compose.yml https://raw.githubusercontent.com/kimai/kimai/main/docker-compose.yml

# Start the stack
docker-compose up -d

# Wait 30 seconds for initialization, then check logs
docker-compose logs -f kimai

Access Kimai at http://localhost:8001 with default credentials:

• Username: susan_super
• Password: kitten

Critical: Immediately change the default password in Settings > User Profile.

Method 2: SSH with Git & Composer

For production servers with full control:

# Clone the repository
git clone -b main https://github.com/kimai/kimai.git
cd kimai

# Install PHP dependencies
composer install --no-dev --optimize-autoloader

# Create .env file from template
cp .env.dist .env

# Edit database credentials
nano .env
# Set DATABASE_URL=mysql://user:password@localhost:3306/kimai

# Create database
php bin/console kimai:install -n

# Create admin user
php bin/console kimai:user:create admin admin@example.com ROLE_SUPER_ADMIN

# Set proper permissions
chown -R www-data:www-data var/
chmod -R 755 var/

System Requirements Check

Before installation, verify your server meets these non-negotiable requirements:

# Check PHP version (must be 8.1.3+)
php -v

# Verify required extensions
php -m | grep -E 'gd|intl|json|mbstring|pdo|tokenizer|xml|xsl|zip'

# Check database version
mysql --version  # Must be MySQL 8.4+ or MariaDB 10.6+

# Ensure memory limit is adequate
php -r "echo ini_get('memory_limit');"  # Should be >= 256M

Pro Tip: For production, use a dedicated subdomain like time.yourcompany.com. Kimai doesn't support subdirectory installations due to its routing architecture.

REAL Code Examples from the Repository

Example 1: Docker Compose Configuration

The official Docker setup uses a production-ready compose file. Here's the essential structure:

# docker-compose.yml - Production-ready Kimai stack
version: '3.5'
services:
  kimai:
    image: kimai/kimai2:apache
    container_name: kimai
    environment:
      # Database connection (uses Docker secrets pattern)
      DATABASE_URL: mysql://kimai:kimaipassword@sqldb/kimai?charset=utf8mb4
      # Application secret (generate with: openssl rand -base64 32)
      APP_SECRET: 'change-this-to-a-random-string'
      # Trust the reverse proxy
      TRUSTED_PROXIES: nginx,localhost,127.0.0.1
    volumes:
      # Persistent storage for uploads and var directory
      - kimai_var:/opt/kimai/var
      # Mount custom plugins here
      - ./plugins:/opt/kimai/var/plugins
    ports:
      - "8001:8001"
    restart: unless-stopped
    depends_on:
      - sqldb

  sqldb:
    image: mysql:8.4
    container_name: kimai_db
    environment:
      MYSQL_DATABASE: kimai
      MYSQL_USER: kimai
      MYSQL_PASSWORD: kimaipassword
      MYSQL_ROOT_PASSWORD: rootpassword
    volumes:
      - kimai_db:/var/lib/mysql
    restart: unless-stopped
    command: --default-storage-engine=innodb

volumes:
  kimai_var:
  kimai_db:

Key points: The TRUSTED_PROXIES setting is crucial when running behind nginx or Cloudflare. The kimai_var volume persists all application data, while the plugins mount lets you add extensions without rebuilding the image.

Example 2: JSON API Authentication & Usage

Kimai's API uses JWT tokens for stateless authentication. Here's how to interact with it:

# api_example.py - Interact with Kimai's JSON API
import requests
import json

# Configuration
KAIMAI_URL = "https://time.yourcompany.com"
API_USER = "api_user"
API_TOKEN = "your-api-token-from-user-profile"

# 1. Authenticate and get JWT token
auth_response = requests.post(
    f"{KAIMAI_URL}/api/auth",
    json={"username": API_USER, "password": API_TOKEN}
)
token = auth_response.json()["token"]

# 2. Set authorization header
headers = {"Authorization": f"Bearer {token}"}

# 3. Get active timesheets (multi-timer support)
active_response = requests.get(
    f"{KAIMAI_URL}/api/timesheets/active",
    headers=headers
)
print(f"Active timers: {len(active_response.json())}")

# 4. Start a new timer for a project
timer_data = {
    "project": 1,  # Project ID
    "activity": 5,  # Activity ID
    "description": "Implementing OAuth2 integration",
    "tags": "api,backend,urgent"
}
start_response = requests.post(
    f"{KAIMAI_URL}/api/timesheets",
    headers=headers,
    json=timer_data
)
print(f"Timer started: {start_response.json()['id']}")

# 5. Stop the timer
timesheet_id = start_response.json()["id"]
stop_response = requests.patch(
    f"{KAIMAI_URL}/api/timesheets/{timesheet_id}/stop",
    headers=headers
)
print(f"Timer stopped. Duration: {stop_response.json()['duration']} seconds")

Pro tip: Store API tokens in environment variables, never in code. The API supports pagination, filtering, and complex queries—perfect for building custom dashboards or Slack integrations.

Example 3: Custom Plugin Skeleton

Extend Kimai by creating a Symfony bundle. Here's the minimal structure:

<?php
// src/Kernel.php - Register your custom plugin
namespace App;

use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;

class Kernel extends BaseKernel
{
    use MicroKernelTrait;
    
    // Kimai automatically scans this directory for plugins
    public function registerBundles(): iterable
    {
        $contents = require $this->getProjectDir().'/config/bundles.php';
        foreach ($contents as $class => $envs) {
            if ($envs[$this->environment] ?? $envs['all'] ?? false) {
                yield new $class();
            }
        }
        
        // Load custom plugins from var/plugins/
        $pluginDir = $this->getProjectDir().'/var/plugins';
        if (is_dir($pluginDir)) {
            foreach (scandir($pluginDir) as $plugin) {
                if ($plugin !== '.' && $plugin !== '..' && is_dir($pluginDir.'/'.$plugin)) {
                    $bundleFile = $pluginDir.'/'.$plugin.'/'.$plugin.'.php';
                    if (file_exists($bundleFile)) {
                        require_once $bundleFile;
                        $class = 'KimaiPlugin\\'.ucfirst($plugin).'\\'.ucfirst($plugin).'Plugin';
                        if (class_exists($class)) {
                            yield new $class();
                        }
                    }
                }
            }
        }
    }
}

// Example plugin: var/plugins/CustomReport/CustomReportPlugin.php
namespace KimaiPlugin\CustomReport;

use App\Plugin\PluginInterface;
use Symfony\Component\HttpKernel\Bundle\Bundle;

class CustomReportPlugin extends Bundle implements PluginInterface
{
    public function getName(): string
    {
        return 'CustomReport';
    }
    
    public function getPath(): string
    {
        return __DIR__;
    }
}

Explanation: Kimai's plugin system leverages Symfony's bundle architecture. Place your plugin in var/plugins/ and Kimai's custom kernel auto-registers it. This enables you to add new menu items, API endpoints, or even completely custom pages without touching core code.

Advanced Usage & Best Practices

Performance Optimization: For teams over 50 users, enable Redis caching:

# In .env, add:
CACHE_DRIVER=redis
REDIS_URL=redis://localhost:6379/0

This reduces database queries by 70% for common reports.

Backup Strategy: Kimai stores critical data in two locations. Your backup script must include:

#!/bin/bash
# backup_kimai.sh - Complete Kimai backup
DATE=$(date +%Y%m%d_%H%M%S)

# Dump database
mysqldump -u kimai -p'password' kimai > kimai_db_$DATE.sql

# Archive var directory (contains invoices, exports, configs)
tar -czf kimai_var_$DATE.tar.gz /path/to/kimai/var/

# Upload to S3 or remote storage
aws s3 cp kimai_db_$DATE.sql s3://backups/kimai/
aws s3 cp kimai_var_$DATE.tar.gz s3://backups/kimai/

Security Hardening: In production, always:

• Set APP_ENV=prod and APP_DEBUG=0
• Configure HTTPS with HSTS headers
• Limit API rate per user: php bin/console kimai:rate-limit api_user 1000
• Regularly run php bin/console kimai:doctor to check system health

Integration Patterns: Use webhooks to notify Slack when projects hit budget limits. Create a cron job that runs php bin/console kimai:invoice:create --user=admin --customer=ACME every month for automated billing.

Kimai vs. The Competition: Why It Crushes Alternatives

Bottom Line: While competitors charge premium prices for basic features, Kimai delivers enterprise functionality at zero licensing cost. The trade-off? You manage hosting. For teams with technical expertise, this saves thousands annually while providing unmatched customization freedom.

Frequently Asked Questions

Q: Can I migrate from Toggl/Harvest to Kimai? A: Absolutely! Kimai includes import tools for CSV/JSON formats. Export your data from Toggl, map the columns to Kimai's format, and run php bin/console kimai:import. Most migrations complete in under an hour.

Q: Is there a mobile app? A: Kimai is progressive web app (PWA) enabled. Visit your Kimai URL on mobile, add to home screen, and get native-app performance without separate downloads. Third-party mobile apps also exist for iOS/Android.

Q: How does Kimai handle offline tracking? A: The PWA caches your timer state locally. When connectivity returns, it syncs automatically. For true offline scenarios, use the API to build a local client that queues requests.

Q: What's the upgrade process like? A: Seamless! Run git pull origin main then php bin/console kimai:update. The built-in doctor command checks compatibility before applying changes. Always backup first—upgrades rarely fail, but safety first.

Q: Can I customize invoice templates? A: Yes! Invoice templates use Twig (Symfony's templating engine). Copy var/invoices/templates/ to create custom designs with your branding, line-item logic, and tax calculations. No limits.

Q: Is Kimai suitable for non-technical users? A: The Cloud version at kimai.cloud offers managed hosting for $5/user/month. Self-hosting requires basic Linux/PHP knowledge, but the interface is intuitive for end-users.

Q: How active is plugin development? A: Extremely! The marketplace grows monthly with plugins for QuickBooks, Slack, GitLab, and custom themes. The developer documentation is comprehensive, and the community provides active support via GitHub Discussions.

Conclusion: Take Control of Your Time Tracking Today

Kimai isn't just another tool—it's a statement. A statement that your time data belongs to you, that open-source can outshine commercial software, and that developers deserve tools built with modern architecture. With its Symfony backbone, JSON API, and infinite extensibility, Kimai grows with your team without inflating your budget.

The five-minute Docker setup means there's zero excuse not to try it today. Whether you're a solo freelancer tired of overpaying for basic timers or a CTO evaluating enterprise solutions, Kimai delivers professional-grade features that adapt to your workflow, not the other way around.

Your move: Head to github.com/kimai/kimai, star the repository, and spin up the Docker compose file. Join thousands of developers who've already made the switch. Your future self—reviewing automated invoices with a single click—will thank you.

Stop renting your tools. Own them. Start with Kimai.