Getting started

This chapter gets you from nothing to a session history flowing to a server. It assumes a server already exists (a teammate runs one, or you do). If you need to stand one up first, Self-hosting does it with a single docker compose up, then come back here.

Terms like session, project, ingest token, and scope appear in passing; the Glossary defines each.

1. Install the client

The akari client runs on macOS, Windows, and Linux. The quickest path is the install script: it downloads the release archive for your platform, verifies it against the release SHA256SUMS, and puts akari on your PATH.

On macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/jssblck/akari/main/scripts/install.sh | sh
akari version

On Windows, from PowerShell:

irm https://raw.githubusercontent.com/jssblck/akari/main/scripts/install.ps1 | iex
akari version

Set AKARI_VERSION (for example v0.1.0) to pin a release instead of taking the latest. Prefer to build from source? With a Go toolchain:

go build -o akari ./cmd/akari
./akari version

The client updates itself in place later with akari update (and akari update --check reports whether one is available without installing it).

2. Point the client at your server

The client authenticates to the server with an ingest token: a push-only credential scoped so it can upload sessions and nothing else. It cannot read your history or mint other tokens.

Mint one from the server’s web UI:

1. Sign in to the server in a browser.
2. Open Account, find API tokens, and create a token with the ingest scope. (The three scopes are ingest, read, and full; see Accounts and sharing.)
3. Copy the token. It is shown once.

Then hand the server URL and token to akari login:

akari login --server https://akari.example.com

login prompts for the token and reads it without echo, so the credential never reaches your shell history. To script it, pipe the token in from wherever you keep it (pass show akari/token | akari login --server https://akari.example.com) rather than passing --token, which would put a live credential in the command line and the process table.

This writes a small config file (server URL and token only) to your OS config directory, with owner-only permissions. That is the client’s entire persistent state; it keeps no session bookkeeping of its own. The client covers the config file and its options in full.

In CI or a container you can skip the file and export the same values instead:

export AKARI_URL=https://akari.example.com
export AKARI_TOKEN=akari_ingest_...
akari sync

AKARI_URL and AKARI_TOKEN override the matching config keys when set, so a one-shot job never has to write a credential to disk. A workstation still wants akari login, because the login agent reads the file.

3. Push your sessions

Do a dry run first to see what the client found and where each session would be filed, without uploading anything:

akari sync --dry-run

Each discovered session prints its resolved project (a git remote, or a local folder when the working directory is not a git repository) or its skip reason. When it looks right, push for real:

akari sync

akari sync discovers the session logs Claude Code, Codex, pi, Cursor, Grok, and OpenCode leave in their standard locations, resolves each to its git project, and streams the new bytes to the server in one pass, then exits. Uploads resume from the server’s cursor, so a re-run only sends what is new.

By default sync stops starting new uploads after five minutes (the file it is on when the limit hits still finishes cleanly); tune it with --time-limit, a Go duration such as 30s or 10m, or 0 to remove the cap:

akari sync --time-limit 30s     # grab a quick sample, then stop

4. Keep it flowing

sync is one-shot. To keep pushing as your agents work, run the daemon, which runs that same sync every 10 minutes:

akari daemon start         # background; prints its PID and log path
akari daemon status        # is it running?
akari daemon stop          # stop it and confirm the single-instance lock is free

Run akari daemon start once and the daemon keeps uploading in the background. daemon stop waits up to 10 seconds for graceful cleanup. If it times out, it leaves the process running and exits non-zero; use --timeout <duration> to wait longer or --force to permit termination after the graceful attempt.

On macOS, start that daemon at login as well:

akari daemon install       # start now, and again at every login
akari daemon uninstall     # stop starting at login

akari watch stays in the foreground and uploads as files change, until you Ctrl-C.

5. Read what you pushed

Open the server in a browser. Your sessions appear on:

• Overview: fleet-wide cost, tokens, and session counts for a trailing window, with an activity heatmap.
• Sessions: every session in one feed, filterable by agent, project, user, and machine.
• Projects: repositories and local folders with lifetime totals and a 30-day token trend.

Click any session to read its full transcript. The web UI is the tour. To read the same history from a coding agent instead of a browser, wire up the MCP endpoint.

When something looks off

The most common first-run snags:

• akari sync uploaded nothing. Run akari sync --dry-run and read the skip reasons. A session whose working directory is not a git repository is filed under a local folder rather than skipped; a session file the client cannot read a header from is skipped entirely.
• A session went to a “local” project you did not expect. Its working directory had no usable git origin remote (not a repo, no origin, several origins, or an unrecognized origin URL), so it was keyed to the machine and folder instead of a shared project. See Glossary.
• akari login succeeds but sync is rejected. The token is probably not an ingest (or full) scope token, or it was revoked. Mint a fresh ingest token and log in again.
• The client cannot find your sessions. akari looks in each agent’s standard location. If yours live elsewhere, add an extra_roots entry to the config; see The client.

Next: The client -> the CLI in depth: how it discovers, resolves, and uploads.