The client

The akari client is the piece that runs on each machine. It finds the session logs your agents write, works out which git project each belongs to, and streams the raw bytes to the server. It keeps almost no state of its own: a config file with a server URL and a token, and nothing else that has to survive a restart. This chapter is the reference for driving it.

Commands

Every command takes --config <path> to point at a config file other than the default. A first Ctrl-C stops sync from starting new files (the one in flight finishes) and winds watch down gracefully; a second exits at once.

login

akari login --server https://akari.example.com --token <token> [--machine <name>]

login writes the server URL and API token to the config file and exits. The token is minted out of band on the server (its account page) and passed in; login does not create it. Use an ingest-scope token for a push-only client, or a full-scope token if the same credential also drives the web API. It preserves any extra_roots and excludes already in the config, so re-running it to rotate a token or move servers does not wipe your discovery settings.

--machine <name> sets the logical machine name this client reports for every session (see the machine config key below). Omit it to keep the OS hostname, or to leave an existing name untouched on a re-run; pass --machine "" to clear it back to the hostname.

sync

akari sync [--dry-run] [--time-limit <dur>] [--concurrency <n>] [--finalize]

sync makes one pass: discover every session file, resolve each to a project, upload what is new, and exit. Because uploads resume from the server's cursor, a re-run sends only bytes the server does not already have.

• --dry-run resolves and reports what would upload, with a skip reason for each file it would not, and uploads nothing. Run it first when setting up a machine.
• --time-limit <dur> caps how long sync keeps starting new uploads, a Go duration such as 30s or 5m (default 5m; 0 removes the cap). The limit gates only when new work begins, so the file being uploaded when the limit elapses runs to a clean stopping point rather than being abandoned mid-stream. Because uploads resume, repeated short runs ingest a backlog in chunks.
• --concurrency <n> bounds how many files upload in parallel (default the CPU count, capped at 8). Each file also parallelizes its own body uploads under a shared limiter, so the file-level cap stays modest on purpose. A given file never races with itself.
• --finalize treats every session as terminal, flushing each one's final turn now instead of waiting for the file to go idle (see "How the upload works" below). It also tells the server the session is finished: the announce marks it terminal and, once the whole transcript has landed, the client asks the server to grade it immediately rather than waiting out the server-side settle window (30 minutes idle). So on an ephemeral host the quality grade is available at the end of the run, in time to report or gate on, instead of long after the host is gone. Use it on a host that disappears right after the sync, a CI job or a cloud sandbox, where neither wait would elapse and the last turn would otherwise never upload and the grade would never land. Reach for it only when every session is genuinely finished: on a workstation where a session may still be running, it would flush a turn mid-stream, so let the idle wait do its job there instead.

watch

akari watch

watch runs in the foreground and uploads sessions as they change, logging to standard error. It holds a single-instance lock for its lifetime, so two watchers cannot run at once. Under the hood it layers three change detectors so nothing is missed: an OS file-system watcher for prompt, debounced uploads; a periodic re-stat of known files to catch changes the OS watcher drops (network filesystems, watch exhaustion); and a slower full rescan that rediscovers roots for newly created files. It does an initial full pass before entering the event loop, ingesting any backlog on startup.

daemon

akari daemon start     # launch watch in the background; prints its PID and log path
akari daemon status    # report whether it is running, and its PID
akari daemon stop      # stop the running watcher

daemon runs the same watch loop as a detached, per-user background process (it is not a system service). It writes a pidfile and a log file under your config directory; start confirms the child took the single-instance lock before returning, and stop verifies a live instance holds it before signaling. This is the steady state on a workstation: run akari daemon start once.

update and version

akari update            # update to the latest release in place
akari update --check    # report whether an update is available, install nothing
akari update --force    # reinstall the latest even if already current
akari version           # print the build version

update is a native updater: it downloads the latest release archive for your platform, verifies it against the release SHA256SUMS, and swaps the binary in place, with no shell or curl involved. On Windows it moves the running executable aside so the update succeeds while akari is running; restart any akari watch or akari daemon afterward to pick up the new version.

Configuration

akari login writes the config; you can also edit it by hand. It is a TOML file in your OS config directory:

Pass --config <path> to any command to use a different file. A full example:

server_url = "https://akari.example.com"
token      = "akari_ingest_..."

# Report every session under one stable machine name instead of the hostname.
machine = "sandbox-pool"

# Discover sessions from extra locations, beyond each agent's standard root.
[[extra_roots]]
agent = "claude"
path  = "/mnt/shared/claude-sessions"

# Skip paths matching these globs during discovery, for sync and watch alike.
excludes = ["**/scratch/**", "*.private.jsonl"]

The keys:

• server_url (required): the server's base URL, no trailing slash.
• token (required): the API token, used as a bearer credential. Ingest scope is the right choice for a push-only client. The file is written with owner-only permissions, since it holds a credential.
• machine (optional): the logical machine name reported for every session this client uploads. Empty falls back to the OS hostname. Set it to give a fleet of ephemeral or containerized hosts (CI jobs, autoscaled workers, throwaway dev containers) one stable identity such as ci or sandbox-pool, so the machine filter does not fill with thousands of single-use hostnames. AKARI_MACHINE overrides it per run.
• extra_roots (optional): additional discovery roots, each an { agent, path } pair where agent is claude, codex, or pi. Use these when your sessions live somewhere other than the standard location.
• excludes (optional): glob patterns of paths to skip, applied to both sync and watch. Patterns match the full path with / separators; **/scratch/** ignores any path with a scratch segment, *.private.jsonl excludes by suffix. Empty discovers everything.

Machine identity

Every session records the machine it came from, a dimension you can filter the feed and each project by. By default that is the OS hostname. On a workstation that is exactly what you want; on ephemeral or containerized hosts it is not, because each run gets a distinct one-off hostname and the machine filter fills with thousands of single-use values that mean nothing.

Give such a fleet one stable logical machine instead. The name is resolved from three sources, highest priority first:

1. the AKARI_MACHINE environment variable, a per-run override that needs no config file (the easy path for a container that sets env far more readily than it writes config);
2. the machine config key, set at akari login --machine <name> or by hand, for a stable per-host or per-fleet name;
3. the OS hostname, the default when neither is set.

The sessions still aggregate by project, user, and agent exactly as before; only the machine label changes, so an ephemeral fleet reporting as ci shows up as one machine rather than polluting the rail.

AKARI_MACHINE is the only environment variable akari itself defines. The client also honors each agent's own root override for discovery (see below).

Discovery

On every run the client looks for session files in each agent's standard location, plus any extra_roots you configured:

Missing roots and excluded paths are skipped without error. For each candidate file, the client peeks the first line to read the working directory and session id, then resolves that directory's git origin remote to a project key. A file whose header cannot be read is skipped entirely; a directory with no usable remote produces a standalone or orphaned project rather than being dropped (Glossary).

How the upload works

The upload protocol is not something you invoke directly, but its shape explains the client's behavior. The upload is resumable and append-only, and the client is stateless across runs:

1. Announce. The client tells the server about a file (its agent, source id, project, branch, machine). The server replies with how many bytes it already holds for that session and a digest of that verified prefix.
2. Reconcile. The client hashes its local file up to the server's cursor. If the digest matches, the prefix is verified and the client resumes from there. If it does not (the file was truncated, rewritten, or rotated), the client resets the session and re-uploads from the start.
3. Stream. The client streams the remaining bytes as newline-aligned chunks. As it goes, it lifts large tool bodies out of the transcript into content-addressed storage: it checks whether the server already holds each body by hash, uploads the ones it does not, and leaves a small reference in the stream. The server re-parses the session moments after chunks land, so a live session appears to grow in the UI as it runs.

Two consequences worth knowing:

• A session's final turn is withheld until its file goes idle. The last turn often has no closing line to mark it complete, so the client waits for the file to be untouched briefly before flushing it. On a host that is torn down right after the sync (CI, a cloud sandbox), that idle wait never elapses, so pass akari sync --finalize to flush the final turns immediately. --finalize also marks each session terminal on the server so its quality grade is computed at the end of the run rather than after the server's own 30-minute settle window, which the host would not be around to see.
• Re-running is cheap and safe. Because the server tracks the cursor and the client re-derives everything from the file, sync after sync uploads only new bytes, and an interrupted upload resumes rather than restarting.

Next: The web UI -> reading the history you just pushed.