Find the logs
By the end you have found the log you need, and read what an agent printed with kraft view logs.
Before you start
$KRAFT_HOMEis~/.kraftunless you set it; see Environment variables. The commands findrun/as Kraft does:$KRAFT_RUN_DIRwhen you set it, elserun/under$KRAFT_HOME.
Find the logs
The server's log is in run/logs/, and each session's log is in its
work item's folder:
run/logs/server.logis the server's own output: startup, shutdown and its reason, errors. A foregroundkraftwrites here as well as to the terminal. Each record is one line (time, level,file.py:line, message), with any traceback whole under it, sogrepfinds the whole record. Kraft moves it toserver.log.1at start once it passes about 8 MB, replacing the last one.run/items/<item id>/sessions/<session id>/session.logis one worker session: everything an agent or command printed. A session from before Kraft kept one folder per item has its log atrun/logs/<session id>.loginstead. Archiving keeps both. Abandoning the item removes its folder, and the logs in it with it; an older session's log inrun/logs/stays.session.times.jsonl, beside the log (<session id>.times.jsonlfor an older session), holds when each line of that session's log was written, one JSON object per line:{"n": <line number>, "t": <timestamp>}.kraft view logsand the item page's log take a line's time from it when the line carries none of its own.
Read a session's log through Kraft rather than by file name:
| Command | What it shows |
|---|---|
kraft view logs ID | The newest session. While the item is stopped, the one that stopped it. |
kraft view logs ID --session SESSION | One session. |
kraft view logs ID -f | A running session, followed. |
A session's log is its output with stdout and stderr merged. Each line shows a
time, a source and the text. The time is when Kraft saw the line, in UTC. It is
--:--:-- for a session Kraft took over after a restart, and for a log from
before Kraft recorded times.
The source is stdout for a plain line. A line of the agent's structured
log is agent (what the agent says), tool (a tool call or its result) or
sys (the session's own start and result lines):
09:30:15 sys init claude-sonnet-5-5
09:30:17 agent I'll start with the failing test.
09:30:18 tool Read(tests/test_board.py)
09:30:21 stdout npm warn deprecated inflight@1.0.6
While the item is stopped, a bare kraft view logs ID shows the session that
stopped it, and names the newest one, such as an auto-escalation, on stderr.
With -f it follows the newest one instead, and names on stderr the session
that stopped the item.
To list an item's session ids:
kraft view events ID --type worker_session_created --json
You know it worked when kraft view logs ID prints the lines the agent or
command wrote. For the server's own log, read the end of run/logs/server.log.
Where an item's files are
Everything a work item produces, except its worktree, is in
run/items/<item id>/:
| Folder | What it holds | Archiving |
|---|---|---|
docs/ | The item's documents: spec.md, plan.md, work_brief.md and the rest its chain writes. | Kept |
history/ | Earlier versions of a document, spec.1.md and on, kept each time a task revises one. | Kept |
filed/ | The copy of each spec or plan filed with the item. | Kept |
sessions/<session id>/ | One session's log, its result file and summary (in out/), and what Kraft handed it. | Kept |
sandbox-home/ | The home directory a sandboxed item's containers share. | Removed |
outputs/ | One folder per task that declared outputs, holding what a later task's reads is given. Added in 2.6 | Removed |
The worktree stays in run/worktrees/<item id>/. Nothing is moved when you
upgrade: an item that ran before this layout keeps its files where it wrote
them, in run/logs/, run/results/, run/attachments/,
run/sandbox-home/<item id>/ and its worktree's .engineering/, and Kraft
reads them there. kraft admin doctor counts the worktrees that still hold a
.engineering/ folder.
Abandoning an item removes its whole folder. Archiving removes the worktree, the sandbox home and the step outputs, and keeps the rest, so an archived item's documents and session logs stay readable on its page.
Next steps
- View verbs: every flag of
kraft view logs - Free disk space: reclaim the space worktrees use
- Back up and restore the database: copy the database before you delete anything by hand
Back up and restore the database
Back up Kraft's database while the server runs, check the backup, restore it, find the copy Kraft makes before an upgrade and roll back to an earlier 2.x release.
Run Kraft as a service
Start Kraft at login and restart it if it exits, set its environment, stop or remove the service, and run a second instance beside the first.