Run the server

Find the logs

Where Kraft writes its server and session logs, how to read a session's log with kraft view logs, and where a work item keeps its files.

By the end you have found the log you need, and read what an agent printed with kraft view logs.

Before you start

  • $KRAFT_HOME is ~/.kraft unless you set it; see Environment variables. The commands find run/ as Kraft does: $KRAFT_RUN_DIR when you set it, else run/ 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.log is the server's own output: startup, shutdown and its reason, errors. A foreground kraft writes here as well as to the terminal. Each record is one line (time, level, file.py:line, message), with any traceback whole under it, so grep finds the whole record. Kraft moves it to server.log.1 at start once it passes about 8 MB, replacing the last one.
  • run/items/<item id>/sessions/<session id>/session.log is one worker session: everything an agent or command printed. A session from before Kraft kept one folder per item has its log at run/logs/<session id>.log instead. Archiving keeps both. Abandoning the item removes its folder, and the logs in it with it; an older session's log in run/logs/ stays.
  • session.times.jsonl, beside the log (<session id>.times.jsonl for 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 logs and 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:

CommandWhat it shows
kraft view logs IDThe newest session. While the item is stopped, the one that stopped it.
kraft view logs ID --session SESSIONOne session.
kraft view logs ID -fA 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>/:

FolderWhat it holdsArchiving
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.6Removed

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

Copyright © 2026