Auth, sync, and local state

How the Desktop Agent talks to the Analog WakaTime backend, and how it behaves when the network is flaky.

Authentication

Device flow (default)

1. CLI calls the gateway device-init endpoint for the desktop agent.
2. You open the printed verification URL and enter the user code (or follow the page instructions).
3. CLI polls the device-poll endpoint until the device is approved or the code expires.
4. Token + expiry are stored in SQLite.

This matches the same family of flows used by other Analog clients, but the agent uses the desktop agent device endpoints.

Email / password

1. CLI POSTs credentials to the gateway login API.
2. On success, the same local session row is written.
3. Transient network errors are retried with backoff according to the agent HTTP retry settings.

Logout

logout clears the local session. The worker may keep sampling windows, but uploads stay paused until you authenticate again. Queued rows are not deleted.

Offline queue

All flushed activity goes to data/agent.db first.

focus samples → in-memory buckets → SQLite pending rows → HTTPS sync → mark synced

Properties:

• Sync runs on a timer inside the worker (default every 10 seconds)
• Each request sends up to the configured batch size (default 200)
• If the gateway is unreachable or returns a soft failure, rows stay pending and the agent tries again later
• status shows Offline sync queue: N so you can see backlog at a glance

This is intentional: tracking should survive VPN drops, laptop sleep, and short API outages.

Sync payload

The worker sends:

{
  "activities": [
    {
      "platform": "Linux",
      "program_name": "code",
      "path": "/usr/share/code/code",
      "filename": "code",
      "time": 120,
      "date": "2026-08-07",
      "hour": 15
    }
  ]
}

Authorization uses the stored bearer/session token for the gateway. The exact HTTP path lives in the agent sync module and points at the desktop activities API behind your configured gateway base URL.

Configuration knobs (compile-time defaults)

Defaults live in the agent configs package. Unless you rebuild with different values, expect:

Setting	Default	Role
Gateway URL	configured build default	API base
Poll interval	10s	How often focus is sampled
Flush interval	10s	How often buckets hit SQLite
Sync interval	10s	How often pending rows upload
Sync batch size	200	Max activities per upload
HTTP retries	high (long-lived retry)	Login / sync resilience
HTTP retry delay	10s	Delay between retryable attempts
Stop timeout	10s	Wait for graceful worker exit
Worker restart delay	10s	Delay after an unexpected worker crash

There is no end-user config file yet: change behavior by rebuilding, or keep using the defaults.

Process and disable flag

Mechanism	Behavior
data/agent.pid	PID of the active worker
data/agent.disabled	Created by stop; start removes it
Missing disabled file	Tracking allowed
Present disabled file	Worker will not be (re)started; existing worker exits

status while enabled will try to ensure the worker is running. While disabled, it will not resurrect it.

Logs

Worker diagnostics go to logs/agent.log, including:

• worker start / stop
• GNOME / KDE helper setup warnings
• active-window backend errors (rate-limited)
• sync postponements

When something looks wrong, start there before reinstalling anything.

Security checklist

• Keep data/agent.db private (it holds your session token)
• Do not commit data/ or logs/ into git
• Run the agent as your desktop user, not as root
• On shared machines, stop + delete data/ when you are done