Time Tracker

A self-hosted Flask time tracker for real project work, not just toy pomodoro sessions.

It is built for people who juggle billable client work, internal work, personal projects, API-driven automation, and backfilled time entry without wanting their data locked into a SaaS. The app stores everything in SQLite, runs well on small hardware, and keeps billing snapshots on entries so reports stay historically accurate even after rates change.

Why this exists

Most lightweight trackers are good at one narrow workflow and awkward at the rest. This project aims to cover the actual messy cases:

• a live timer when you are actively working
• manual logs when you forgot to track something in the moment
• fixed-fee work where you still want to know your effective hourly rate
• client rollups across multiple projects
• standalone projects that do not belong to a client at all
• payment tracking so billed work and collected cash are not treated as the same thing
• API-controlled timers so external tools can start and stop sessions

Core capabilities

Time tracking

• Start, pause, resume, and stop live timers
• Edit running timer notes without stopping the timer
• Adjust the start time of an active timer
• Log manual entries by exact start/end range
• Log hours-only entries when you just want to enter total time
• Keep timer and manual workflows side by side

Project structure

• Standalone projects
• Clients with multiple linked projects
• Business and personal project categories
• Active and archived project states
• Per-project colors and descriptions

Billing and money tracking

• Hourly billing projects
• Fixed-fee projects
• Effective hourly rate calculation for fixed-fee work
• Per-entry hourly snapshots
• Payments ledger
• Incurred Charge, Billed amount, Discounted amount, and Paid amount views

API timer support

• Project-scoped API keys
• Separate API hourly value
• API/manual overlap billing rules
• API timer status, start, and stop endpoints

Reporting and data control

• Dashboard summaries
• Project detail views
• Client rollups
• Date-filtered reports
• CSV export
• Full SQLite backup export/import

Stack

• Flask
• SQLite
• Waitress
• Vanilla HTML/CSS/JS
• Docker Compose for simple self-hosting

Quick start

Local run

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:PORT = "5300"
python app.py

Then open http://127.0.0.1:5300.

Docker

cp .env.example .env
# edit .env and set a real SECRET_KEY
docker compose up -d --build

By default the app publishes on host port 5300, but you can change that in .env.

Configuration

The app reads these environment variables:

• PORT: listening port. Default is 5000 for python app.py
• HOST: listening host. Default is 0.0.0.0
• SECRET_KEY: Flask session secret. Set this in production
• FLASK_DEBUG: set to 1 only for local development
• APP_TIMEZONE: app wall-clock timezone for stored timestamps

API timers

Each project can have its own API key, API hourly rate, and API/manual overlap policy from the project edit screen.

Endpoints

• POST /api/timer/start
• POST /api/timer/stop
• GET /api/timer/status

Authenticate with either:

• X-Api-Key: <project api key>
• Authorization: Bearer <project api key>

POST /api/timer/start

Optional JSON fields:

• notes
• started_at
• is_billable

POST /api/timer/stop

Optional JSON fields:

• notes
• ended_at

Overlap behavior

Per project, you can choose:

• Count manual + API time separately
• Suppress API cost while manual timed work overlaps

That second mode is useful when external automation is tracking context, but you only want the manual timed work to count for overlapping billable windows.

Data storage

• SQLite database path: instance/time_tracker.db
• In Docker, SQLite is persisted under ./data/time_tracker.db through the mounted /app/instance volume
• The app creates the database and tables automatically on first boot
• Timestamps are stored as local wall-clock values in the app's configured timezone

Development

Run the test suite:

python -m unittest discover -s tests

Security notes

• Do not commit .env
• Do not commit live database files
• Do not commit generated project API keys
• Rotate any keys used in private environments before exposing a public instance
• Set a real SECRET_KEY before deploying anywhere real

Support

If Time Tracker helps you stay organized, recover missed billable hours, or run your own self-hosted workflow with less friction, consider supporting the project. Support helps fund ongoing polish, new features, and the time it takes to keep the app useful in real-world work.

Support the project: https://www.buymeacoffee.com/benralph