How-To · reference

Where everything lives

Kaptain keeps everything in one data folder plus one .planning/ folder inside your chosen project. Know these two places and you know the whole footprint.

The map

Thing	Where
Configuration	`kaptain.json` in the data folder — treat it as private; it holds this device's credentials
Conversations	`sessions.db`
Models, agents, provider keys	`models.db`
Kapsules (agents)	`kapsules/<name>/kapsule.json` — persona, schedule, grants; all editable
Project working notes	`.planning/` inside your chosen project folder
Logs	`kaptain.log` in the data folder; `kaptain status` prints the path
Server pid (when started with `start`)	`kaptain.pid`
Update backup	previous binary kept as `<binary>.bak` next to the installed one

Per-OS data folder

OS	Data folder
Linux	`~/.local/share/kaptain/`
Windows	`%LOCALAPPDATA%\Kaptain`
macOS	`~/Library/Application Support/Kaptain`

Back up / move a box

kaptain stop — never copy the databases under a running server.
Copy the data folder (and your project's .planning/ if you want the working notes).
On the new machine: install Kaptain, put the data folder in place, start.
The device certificate is per-machine: run kaptain device register on the new box (guide) — it issues a fresh access code, and your devices re-pair once.

Overriding the data folder

KAPTAIN_DATA_DIR=/path kaptain start points everything at a different folder — useful for a sandboxed second instance on the same machine. It is the only override honoured, deliberately.

Agent-readable version: index.md · Every claim on this page was exercised on a real install before being written. Something missing that cost you time? That is a documentation bug — tell us.