If you bill clients by the hour, or you just want to know where your workday actually goes, a spreadsheet only gets you so far. Kimai is a free, open-source time tracking tool you can run entirely on your own hardware, and it happens to install cleanly in a Proxmox VE LXC container in about ten minutes.
This guide walks through the whole process on a fresh Proxmox VE 8.x or 9.x host: what Kimai actually does, why you'd run it yourself instead of paying for Toggl or Clockify, and the exact steps to get a working instance you can log into from your browser. No prior Proxmox experience required — if you've never created a container before, you're in the right place.
What You'll Learn
- What Kimai is and who actually needs it
- What an LXC container is and why it's the right fit for an app like this
- How to deploy Kimai using the community-scripts helper script
- What each part of the install script is doing under the hood
- How to log in, change the default password, and fix the errors people usually hit
What Is Kimai?
Kimai is a self-hosted time tracking application. You start a timer when you begin a task, stop it when you're done, and Kimai logs the entry against a project, an activity, and (optionally) a customer. Over time you end up with a searchable history of exactly how your hours were spent, which you can turn into invoices, export as a CSV, or just stare at when you're wondering where Tuesday went.
It's built on PHP and Symfony, stores its data in a MySQL-compatible database (MariaDB in this guide), and ships with a web interface that works fine on a phone if you need to punch in from your couch. Kimai isn't tied to any subscription — once it's running, it's yours, and there's no per-seat pricing to worry about as your team grows.
Beyond the basic start/stop timer, it handles hourly billing rates per project or per user, generates PDF invoices, and produces reports broken down by customer, project, or team member. None of that is bolted on as a premium add-on — it's all part of the same free package.
Kimai vs. Hosted Alternatives
Here's roughly how it stacks up against the SaaS tools most people try first:
| Feature | Kimai (self-hosted) | Toggl / Clockify (hosted) |
|---|---|---|
| Monthly cost | $0, forever | Free tier, then per-user pricing |
| Data location | Your own server | Vendor's cloud |
| Invoicing | Included | Often a paid add-on |
| Setup effort | ~10 minutes with the script below | Instant sign-up |
| Offline access | Works on your LAN even without internet | Requires internet |
Why Run Kimai in Proxmox VE?
You could sign up for a hosted time-tracking SaaS in about ninety seconds. So why bother self-hosting?
The honest answer is control. Your timesheets and client data stay on hardware you own, not on someone else's servers. There's no monthly fee that scales with your headcount, and no risk of a vendor changing their pricing tier and locking a feature you rely on behind a paywall. If you're already running Proxmox VE for a homelab or a small business, adding Kimai costs you a few gigabytes of disk and about 2 GB of RAM — a rounding error on most setups.
Running it in an LXC container specifically (rather than a full virtual machine) keeps the overhead low. An LXC container is a lightweight form of virtualization that shares the host's Linux kernel instead of emulating its own virtual hardware — think of it as an isolated Linux environment rather than a full separate computer. That means faster boot times, less RAM wasted on a duplicate OS kernel, and a footprint small enough that you won't think twice about running Kimai alongside a dozen other self-hosted apps.
Prerequisites
Before you start, make sure you have:
- A working Proxmox VE 8.x or 9.x host with internet access
- Root access to the Proxmox VE shell (via the web UI's >_ Shell button on the node, or SSH)
- At least 7 GB of free space on the storage you plan to use for the container, plus roughly 2 GB of RAM to spare
- A rough idea of your network setup — DHCP is fine for testing, but you'll probably want a static IP for anything you keep long-term
You don't need to pre-install PHP, MariaDB, or Apache. The install script handles all of that inside the container automatically. You also don't need Docker — this method builds a native Debian container instead of running Kimai in a Docker image, which keeps resource usage lower and makes backups a matter of snapshotting one LXC container.
Step-by-Step: Installing Kimai in an LXC Container
Step 1: Open the Proxmox VE Shell
Log into the Proxmox VE web interface, click your node's name in the left-hand tree (not a specific VM or container — the node itself), and click >_ Shell near the top right. This drops you into a root terminal on the Proxmox host, which is where the container gets created from.
Step 2: Run the Kimai Installer Script
Paste this command into the shell and press Enter:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/kimai.sh)"This comes from the Proxmox VE Community Scripts project — a widely used collection of installer scripts maintained by the homelab community that automate the tedious parts of setting up an LXC container for a specific app. Instead of manually creating a container, installing PHP, configuring a database, and downloading Kimai by hand, the script does all of it for you in one pass.
Step 3: Walk Through the Setup Prompts
An interface (built with whiptail) will ask a few questions. For a first install, the default answers work fine:
- Advanced Settings — choose "No" unless you want to change the default CPU, RAM, disk, or hostname before creation
- The script confirms the container type: unprivileged, Debian 13, 2 CPU cores, 2048 MB of RAM, and a 7 GB disk
Hit Enter to confirm and let it run. On a decent internet connection this takes somewhere around 5 to 8 minutes — most of that time is spent downloading the Debian template, installing PHP dependencies through Composer, and pulling the latest Kimai release from GitHub.
Step 4: Note the Output
When the script finishes, it prints a summary block with the container's ID and IP address, something like:
Kimai should be reachable by going to the following URL.
http://192.168.1.150
Kimai-Credentials
Kimai Database User: kimai
Kimai Database Password: xxxxxxxxxxxxx
Kimai Database Name: kimai_dbCopy that IP address down — you'll need it for the next step. The database credentials are saved inside the container at ~/kimai.creds if you lose them.
Step 5: Log Into Kimai
Open a browser and go to http://<container-ip> (no port number needed — it's served on standard port 80 through Apache). You'll land on the Kimai login page. Sign in with the default admin account:
- Username:
admin - Password:
community-scripts.org
Change that password immediately — go to your user profile in the top-right menu, then Edit, and set something only you know. Leaving the default password on an internet-facing service is how homelabs get broken into.
Step 6: Create Your First Project and Timer
Kimai organizes time entries under a hierarchy: Customer > Project > Activity. Under Administration, create a customer (even "Personal" works if this is just for you), then a project under that customer, then an activity like "Development" or "Support." Once those exist, the big green "Start" button on the dashboard lets you begin tracking time against them immediately.
Commands Explained
A few things worth understanding about what just ran, in case you need to troubleshoot later:
| Command / Path | What It Does |
|---|---|
bash -c "$(curl -fsSL ...)" | Downloads the install script and runs it immediately without saving it to disk first. |
/opt/kimai | Where the Kimai application files live inside the container. |
bin/console kimai:install | Kimai's own setup command — it creates the database schema and default settings on first run. |
bin/console kimai:update | Runs during upgrades to apply any new database migrations after files are updated. |
systemctl status apache2 | Run this inside the container if the web page won't load — it tells you whether the web server is actually running. |
Common Errors
A few things trip people up on this particular script, based on how it's built:
"Setup Kimai" hangs or exits with code 0 partway through. This has shown up on some Debian 13 installs where the automated admin-user creation step (which uses expect to script an interactive prompt) fails silently. If the script finishes but you can't log in with the default admin account, shell into the container with pct enter <CTID>, cd /opt/kimai, and run bin/console kimai:user:create admin admin@example.com ROLE_SUPER_ADMIN manually — it'll prompt you for a password directly instead of relying on the scripted input.
Blank white page instead of the login screen. Almost always a PHP error being swallowed by Apache. Check /var/log/apache2/error.log inside the container for the actual stack trace.
Can't reach the IP address at all. Confirm the container actually got an IP — run pct exec <CTID> -- ip a from the Proxmox shell. If it shows no address, your network bridge or DHCP server is the problem, not Kimai.
Troubleshooting
If login works but the dashboard looks broken or throws a 500 error after you start creating projects, it's usually one of two things. First, check that MariaDB is actually running: systemctl status mariadb inside the container. Second, check disk space with df -h — a full disk on a 7 GB container is easy to hit if you've imported a large CSV of historical time entries, and Kimai fails ungracefully when it can't write to its cache directory.
If you need to reset the admin password without going through the UI, run this inside the container from /opt/kimai:
bin/console kimai:user:password adminIt'll prompt you for a new password and update it directly in the database.
For anything stranger, pull the Apache error log and the Kimai-specific log at /opt/kimai/var/log/prod/prod.log — between the two, you'll almost always find the actual root cause rather than a generic error page.
One more thing worth checking if pages load slowly the first time you click around: Kimai caches a lot of Symfony configuration on first request in production mode, so that initial page load after a fresh install or update can take a few extra seconds while the cache warms up. Subsequent loads are fast. If it stays slow permanently, the container is probably underpowered for your usage — bump the RAM allocation from Proxmox VE's Hardware tab for the container rather than fighting it in software.
Best Practices
Take a snapshot of the container right after the initial install and password change, before you start entering real data. Proxmox VE snapshots are near-instant on ZFS-backed storage and give you a clean rollback point if you break something experimenting with settings later.
Set a static IP for the container rather than leaving it on DHCP. Bookmarking a Kimai instance that quietly changes IP addresses after a router reboot is a good way to lose access to your own timesheets at the worst moment — right before a client invoice is due.
Put Kimai behind a reverse proxy with a real SSL certificate if you're going to access it from outside your home network. Running it over plain HTTP on the open internet means your login credentials travel in cleartext. A tool like Nginx Proxy Manager or Traefik running in its own LXC container handles this without much extra setup.
Back up the container regularly through Proxmox's built-in vzdump scheduler, or through Proxmox Backup Server if you're running one. Time tracking data that feeds into client invoices isn't something you want to lose because a disk failed on a Tuesday.
Frequently Asked Questions
Do I need Docker to run Kimai on Proxmox?
No. This method installs Kimai natively inside a Debian LXC container using Apache and MariaDB directly. Docker works too if you prefer it, but it adds an extra layer of overhead that isn't necessary for a single-instance homelab deployment.
Can multiple people use the same Kimai instance?
Yes. Kimai supports multiple user accounts with different roles, from basic time-tracking users up to super admins who can manage billing rates and export data. Create additional users under Administration > Users.
Is Kimai really free, or is there a paid tier?
The self-hosted version used in this guide is fully free and open source under the AGPL license. Kimai's creators also sell a hosted cloud version with support included, but nothing in the self-hosted edition is locked behind a paywall.
How do I update Kimai later?
Re-run the same install command from the Proxmox shell: bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/kimai.sh)". The script detects the existing installation and runs its update path instead of creating a new container.
Can I export my time entries?
Yes — Kimai supports CSV, PDF, and Excel exports from the timesheet view, and it can generate PDF invoices directly if you set up customer billing rates.
Final Thoughts
Kimai is one of those tools that pays for itself in the first week just by making it obvious where your time actually goes. Running it in an LXC container keeps the resource cost low enough that there's not much reason not to try it, especially if you're already running Proxmox VE for other self-hosted services. Set the static IP, change that default password, put a backup schedule on it, and you've got a time tracker that answers to nobody but you.