Operate a Kraft server
The day-to-day care of a Kraft install: backups, logs, disk space, a second instance, and running Kraft as a service.
Before you start
- Everything below lives under
$KRAFT_HOME, which is~/.kraftunless you set it.run/holds the state,templates/holds the config. See Data and privacy for what each file holds. - The commands assume the default home. Put your own path in place of
~/.kraftif you moved it. - If Kraft runs as a service,
kraft admin stopdoes not keep it stopped: the service manager starts it again. Where a step says to stop the server, runkraft admin uninstall-serviceinstead, andkraft admin install-servicewhen you are done.
Back up the database
run/orchestrator.db holds every work item, event, session and review
thread. Kraft runs SQLite in WAL mode, so recent writes can sit in
orchestrator.db-wal beside it. Copying orchestrator.db alone while the
server runs can give you a copy that is missing them, or one that does not
open.
Use SQLite's online backup, which is safe while the server runs:
sqlite3 ~/.kraft/run/orchestrator.db ".backup '$HOME/kraft-backup.db'"
Or stop the server first, then copy the file:
kraft admin stop
cp ~/.kraft/run/orchestrator.db ~/kraft-backup.db
kraft admin start --detach
Back up templates/ too. It is your config, and it is small. See
Keep your templates in git.
You do not need to back up run/index.db. It is the search index, and
kraft admin reindex rebuilds it.
To restore, stop the server, put the backup in place as
run/orchestrator.db, delete any orchestrator.db-wal and
orchestrator.db-shm beside it, and start the server again.
Verify the backup
sqlite3 ~/kraft-backup.db "PRAGMA integrity_check; SELECT count(*) FROM work_items;"
It prints ok, then the number of work items.
Find the logs
All logs are in run/logs/.
| File | Holds |
|---|---|
server.log | The server's own output: startup, shutdown and its reason, errors. A foreground kraft writes here as well as to the terminal. Kraft moves it to server.log.1 at start once it passes about 8 MB, replacing the last one. |
<session id>.log | One worker session: everything an agent or command printed. Kraft never deletes these. |
Read a session's log through Kraft rather than by file name:
kraft view logs ID # the item's latest session
kraft view logs ID --session SESSION # one session
kraft view logs ID -f # follow a running session
kraft view events ID --type worker_session_created --json lists the item's
session ids.
Reclaim disk space
Each work item gets a git worktree in run/worktrees/<item id>/, a full
checkout of its repo, plus any dependencies its setup command installed. That
adds up.
A worktree is removed when the item is abandoned or archived:
- Abandon a work item you no longer want:
kraft item abandon ID --yes. It removes the worktree and deletes the item's local branch. It destroys uncommitted work. - Archive a completed or abandoned item from the board's Done group, or
with
POST /api/work-items/ID/archive. It removes the worktree, the local branch and the attachment copies inrun/attachments/, and keeps the item's record. - Auto-archive.
archive.after_daysinpolicy.yamlarchives completed and abandoned items that old. The shipped file sets30. Lower it to reclaim space sooner. See Policy.
kraft item complete and kraft item cancel keep the worktree until the
item is archived.
Session logs in run/logs/ and result files in run/results/ stay after
archiving. Delete old ones by hand if they grow, with the server stopped.
To see what uses space:
du -sh ~/.kraft/run/*
Run two instances
Two instances need separate homes and separate ports. A second server on the same port refuses to start and names the one already there.
Start the second instance once on a free port. The first start seeds its
templates/:
KRAFT_HOME=~/kraft-staging KRAFT_PORT=8766 kraft admin start --detach
Then write the port into that home's access.yaml, so the server and the
kraft command find it without KRAFT_PORT. A port given only as KRAFT_PORT
or --port is not saved, and every other command would still dial 8765:
printf 'port: 8766\n' >> ~/kraft-staging/templates/access.yaml
Create templates/ only this way. Kraft seeds a home only when templates/
does not exist yet, so a directory you made by hand stays empty.
Run every command for that instance with the same KRAFT_HOME:
KRAFT_HOME=~/kraft-staging kraft view list
KRAFT_HOME=~/kraft-staging kraft admin stop
Workers inherit their instance's KRAFT_HOME, so their own kraft calls
reach the instance that started them. An agent you run yourself reaches the
instance its environment names, so start it with the same KRAFT_HOME to use
the second one.
Run Kraft as a service
A service starts Kraft at login and restarts it if it exits:
kraft admin stop
kraft admin install-service
On macOS this writes a launchd agent,
~/Library/LaunchAgents/com.kraft.daemon.plist, and loads it. On Linux it
writes a systemd user unit, ~/.config/systemd/user/kraft.service, and enables
it. install-service refuses while a server is running, so stop it first.
The service gets the environment of the shell you ran install-service from:
PATH, and KRAFT_HOME, KRAFT_RUN_DIR, KRAFT_TEMPLATES_DIR,
KRAFT_SKILLS_DIR, KRAFT_HOST and KRAFT_PORT when set. Run it from a shell
where claude, git, gh and your other tools are on PATH. To pick up a
changed PATH later, run kraft admin uninstall-service, then
install-service again.
There is one service per user. Its launchd label and systemd unit name are fixed, so run a second instance by hand.
To remove it:
kraft admin uninstall-service
Verify the service
kraft admin restart
kraft admin health
restart goes through the service manager when a service is installed.
health exits 0 once the server is back.