Build a coding record you actually own.

Hosted beta setup

1. 1

   Create your account

   Open Trackam, choose a username, enter your email, and use a password of at least eight characters. The beta currently accepts up to 100 developer accounts.

2. 2

   Verify your email

   Open the verification message Trackam sends you. Verification is required for password recovery and optional weekly coding summaries.

3. 3

   Copy your editor configuration

   Trackam never displays the raw API key on screen. Use Copy config securely immediately after signup or key regeneration.

4. 4

   Start coding

   Open a project and edit a file. The official WakaTime plugin sends small heartbeat events to Trackam in the background.

5. 5

   Confirm the connection

   Return to the dashboard. The “coding now” status should turn on and today’s heartbeat count should begin increasing.

What Trackam records

1. Install the WakaTime plugin

2. Add your Trackam configuration

After signup, select Copy config securely. Paste the copied text into the WakaTime configuration file for your operating system.

[settings]
api_url = https://trackam.click/api/v1
api_key = your-one-time-trackam-api-key

3. Verify heartbeat delivery

• Edit and save a code file for at least one minute.
• Open Trackam and look for the green “coding now” indicator.
• Confirm that today’s heartbeats, coding time, project, and language appear.
• If the editor still points to WakaTime, restart it after changing the configuration.

API-key safety

Trackam stores only a SHA-256 lookup hash of each API key. The raw value is delivered once during signup or regeneration with a non-cacheable response. It is copied directly to your clipboard and never rendered in the dashboard.

Available date ranges

How coding time is calculated

Trackam sorts your heartbeats and measures the gap between consecutive events. A positive gap counts only when it is smaller than your heartbeat timeout. The default timeout is 900 seconds (15 minutes), and you can set a value from 60 to 3,600 seconds in Settings. Larger gaps are treated as breaks.

Breakdowns and daily summaries

The overview groups coding seconds by project, language, editor, and operating system. Daily totals and breakdowns are maintained during ingestion for fast dashboard reads. Changing your timezone or heartbeat timeout rebuilds your summaries and coding intervals so historical views remain consistent with the new preference.

GitHub README badges

Open Dashboard → GitHub badges. Choose a type and range, preview the result, enable public badges, then copy the generated Markdown into a GitHub profile or project README.

![Trackam coding time](https://trackam.click/api/badges/your-username/coding-time.svg?range=7d)

Portfolio widget

The responsive widget is designed for developer portfolios. Choose a period and theme, preview it privately, turn on portfolio publishing, and paste the generated iframe into your site.

<iframe
  src="https://trackam.click/embed/your-username?range=30d&theme=dark"
  title="My Trackam coding activity"
  loading="lazy"
  style="width:100%;height:250px;border:0"
></iframe>

Generated proof-of-work page

A proof page is a shareable webpage covering a selected period. It contains aggregate coding time, active days, streaks, projects, languages, tools, daily totals, and a verification ID. Use it for monthly reviews, applications, client updates, or a portfolio case study.

Build your own component

The public portfolio JSON endpoint sends aggregate data with CORS enabled, so a custom portfolio frontend can render Trackam activity without embedding the built-in widget.

const stats = await fetch(
  "https://trackam.click/api/portfolio/your-username?range=30d"
).then(response => response.json());

Coding goals

Set a daily target and a rolling seven-day target from the dashboard. Progress updates as daily summaries are maintained, using your account timezone and heartbeat timeout.

Contribution heatmap

The contribution-style heatmap shows up to 366 local calendar days. Colour intensity represents coding time for each day; hovering or focusing a cell reveals its date and duration. This heatmap is private inside your dashboard.

Export your data

Exports are authenticated and contain your raw heartbeat records. Use JSON for backup or scripts, and CSV for spreadsheets or external analysis.

Private friend leaderboards

Trackam has no public global ranking. Every leaderboard is an invite-only group. Members see aggregate coding time, rank, top language, and heartbeat count for people who explicitly joined.

1. 1

   Create a group

   Choose a name. You become the owner and first member.

2. 2

   Share the invite link

   Send the generated /app?invite=CODE URL only to friends you want in the group.

3. 3

   Compare a range

   Rankings support today, week, month, and quarter views.

4. 4

   Manage membership

   Owners can remove members, rotate the invite code, or delete the group. Non-owners can leave at any time.

Workspace lifecycle

Roles and permissions

What companies can see

Company API overview

Grant owner access

Set OWNER_EMAILS to a comma-separated list of existing Trackam account emails. Sign in through the normal dashboard first, then open /admin.

OWNER_EMAILS=owner@example.com,second-owner@example.com

Suspension behavior

Authentication

Core endpoints

Send a heartbeat

curl -u 'YOUR_TRACKAM_API_KEY:' \
  -H 'Content-Type: application/json' \
  -d '{"entity":"src/index.ts","type":"file","category":"coding","time":1760000000,"project":"trackam","language":"TypeScript"}' \
  https://trackam.click/api/v1/users/current/heartbeats

Ranges and responses

Analytics endpoints accept the ranges supported by their screen—commonly today, week, month, quarter, six_months, and total. Successful JSON responses use normal HTTP status codes; validation and authentication failures include a readable error field.

Docker Compose

git clone https://github.com/OutstandingVick/trackam.git
cd trackam
cp .env.example .env
# Replace JWT_SECRET and MONITORING_TOKEN in .env
docker compose up -d --build

Compose starts PostgreSQL, applies every numbered migration in order, and starts the app only after the database is healthy and migrations succeed. Open http://localhost:3000.

Local development

npm ci
cp .env.example .env
npm run migrate
npm run dev

Essential configuration

How the pieces fit

Deploy on Railway

1. 1

   Create the services

   Connect the GitHub repository to an application service and add managed PostgreSQL in the same private environment.

2. 2

   Add production variables

   Set DATABASE_URL, BASE_URL, JWT_SECRET, MONITORING_TOKEN, MAX_USERS=100, and OWNER_EMAILS. Add SMTP before public signup.

3. 3

   Deploy from main

   railway.json builds the Dockerfile, runs migrations before release, starts the server, and gates success on /readyz.

4. 4

   Attach the domain

   Add your custom domain in Railway, copy its DNS target into your registrar, wait for HTTPS, then update BASE_URL.

Health and monitoring

Alert on readiness failures, repeated 5xx responses, high database latency, disk pressure, TLS expiry, backup age, and approaching the 100-user beta cap. Never expose the monitoring token in a public uptime check.

Release path

Backups and recovery

Rollback rules

Roll the application image back when readiness or smoke checks fail. Keep schema changes backward-compatible across the rollback window. A database restore is destructive and should only follow an explicit incident decision with a fresh final backup.

Data boundaries

Secret-handling rules

• Keep .env, Railway variables, SMTP passwords, database URLs, and Paystack keys out of Git.
• Use different random values for JWT_SECRET, MONITORING_TOKEN, and billing encryption.
• Never embed a Trackam API key in a public portfolio, browser bundle, screenshot, issue, or support message.
• Restrict database and metrics access to private networks or authenticated clients.
• Review dependency, secret-scanning, and container findings before each production release.

If a key or secret leaks