Configuration
Environment variables
Every KRAFT_* variable Kraft reads or sets, and the other variables it reads or passes to workers.
Set by an operator
Set these in the shell that starts kraft, or in the service unit.
kraft admin install-service copies KRAFT_HOME, KRAFT_RUN_DIR,
KRAFT_TEMPLATES_DIR, KRAFT_SKILLS_DIR, KRAFT_HOST, KRAFT_PORT and
PATH into the unit it writes.
| Variable | Default | What it does |
|---|---|---|
KRAFT_HOME | ~/.kraft | The directory Kraft keeps everything in. just dev points it at .dev/ so a dev instance cannot touch the real one. |
KRAFT_RUN_DIR | $KRAFT_HOME/run | Databases, logs, worktrees, the pidfile and the MCP token. |
KRAFT_TEMPLATES_DIR | $KRAFT_HOME/templates | The config directory: policy.yaml, repos.yaml, access.yaml, chains and the rest. |
KRAFT_SKILLS_DIR | $KRAFT_HOME/skills | Where a skill file overrides the bundled one of the same name. Usually absent. |
KRAFT_HOST | bind in access.yaml | The address the server binds and the CLI connects to. kraft admin start --host overrides it. |
KRAFT_PORT | port in access.yaml | The port the server binds and the CLI connects to. kraft admin start --port overrides it. |
KRAFT_NO_UPDATE_CHECK | unset | Any value turns off the release check in kraft admin start and kraft admin doctor. |
KRAFT_EDITOR | the OS opener (open, xdg-open) | The editor kraft view doc --open and the board use when none is named: code, cursor, zed or obsidian. |
KRAFT_EMBED_CACHE | $XDG_CACHE_HOME/kraft/fastembed, else ~/.cache/kraft/fastembed | Where semantic search keeps its model weights. |
KRAFT_BD_CWD | unset | The directory bd runs in for bead operations and bead search, instead of each repo. |
KRAFT_FRONTEND_DIST | the bundled web UI | The built web UI to serve. just dev points it at Vite's output. |
KRAFT_INDEX_REPOS | unset | More repo paths for the search index to scan, besides the connected ones, separated by :. Used by end-to-end tests. |
Passed to workers
Kraft sets these in each agent session's environment. A worker's own kraft
command and MCP client read them.
| Variable | Set to | What it does |
|---|---|---|
KRAFT_WORK_ITEM_ID | The work item's id | Marks the session as a Kraft worker. The CLI and MCP server use it as the default work item, and refuse a worker's decisions about its own item (see MCP tools). Not set for an escalation turn, which runs as a person's session. |
KRAFT_SESSION_ID | The session's id | Sent with each API call, so a route can tell the calling session apart. |
KRAFT_RESULT_PATH | A file under run/ | Where the agent writes its result: status, concerns, a question, usage. Subprocess tasks get it too. See Result file. |
KRAFT_REVIEW_PACKAGE | A file under run/ | For a review task: the commit list, files changed and diff to review. |
KRAFT_PERMISSION_FAIL_CLOSED | 1 | Set when a hooked harness (Cursor, Codex) runs under an allowed_tools list. The hook then denies a call when it cannot reach Kraft. See Permission gate. |
KRAFT_DAEMON_PID, KRAFT_DAEMON_PORT | The server's pid and port | Lets a worker tell the Kraft server apart from a stray process before it kills anything on a port. |
A worker also gets KRAFT_HOME, KRAFT_RUN_DIR, KRAFT_TEMPLATES_DIR,
KRAFT_SKILLS_DIR, KRAFT_HOST and KRAFT_PORT when the server has them, so
its kraft command reaches the instance that started it.
Set by Kraft for itself
You do not set these.
| Variable | What it does |
|---|---|
KRAFT_CLIENT | Set to mcp by kraft admin mcp, so the API can tell an agent's call from a person's. |
KRAFT_DETACHED | Set on the child of kraft admin start --detach, so kraft admin restart starts it the same way. |
KRAFT_LOG_REDIRECTED | Set on the same child, whose output already goes to run/logs/server.log. |
Other variables
| Variable | Read by | What it does |
|---|---|---|
PATH | the server | Where Kraft finds claude, the other agent CLIs, git, gh, glab and bd. Under a service, this is the unit's PATH, not your shell's. |
ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN | workers | Claude Code's credentials. Passed to every worker, sandboxed or not. |
CODEX_API_KEY, GEMINI_API_KEY, CURSOR_API_KEY, and other agents' keys | workers | Not passed by default. Name one in the repo's env_passthrough. |
CODEX_HOME | kraft admin permission-hook codex | Codex's config directory. Default ~/.codex. |
NO_COLOR | the CLI | Turns off colored output. |
PAGER | the CLI | The pager for long output. Default less -R. |
SHELL | kraft admin doctor | Which shell's completion line to suggest. |
XDG_CONFIG_HOME | kraft admin install-service | Where the systemd user unit goes. Default ~/.config. |
XDG_CACHE_HOME | semantic search | The base of the default KRAFT_EMBED_CACHE. |
SSL_CERT_FILE | the sandbox | An extra CA bundle a sandboxed worker trusts, for a TLS-intercepting proxy. |
A worker's environment is an allowlist. Besides the variables above, it gets
HOME, USER, LOGNAME, SHELL, LANG, LC_ALL, TERM, TZ, TMPDIR,
SSH_AUTH_SOCK, the proxy variables and the CA variables, then the repo's
env and env_passthrough. See the
env field in repos.yaml. Kraft does not read
EDITOR or VISUAL.