Environment variables
Kraft reads and sets environment variables in four groups: variables you set, variables Kraft passes to workers, variables Kraft sets for itself, and other variables it reads.
Variables you set
Set these in the shell that starts kraft, or in the service unit. kraft admin install-service copies KRAFT_HOME, KRAFT_RUN_DIR, KRAFT_CONFIG_DIR (and a KRAFT_TEMPLATES_DIR the shell still has), 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_CONFIG_DIR | $KRAFT_HOME/config | The config directory: policy.yaml, repos.yaml, access.yaml, chains and the rest. See Configuration. |
KRAFT_TEMPLATES_DIR | unset | The 1.x name of KRAFT_CONFIG_DIR. Kraft reads it when KRAFT_CONFIG_DIR is unset, and sets it nowhere. Use KRAFT_CONFIG_DIR. |
KRAFT_SKILLS_DIR | $KRAFT_HOME/skills | Where a skill file overrides the shipped one of the same name. Usually absent. |
KRAFT_HOST | bind in access.yaml | The address the server binds and the CLI connects to. access.yaml says which of this, --host and bind wins. |
KRAFT_PORT | port in access.yaml | The port the server binds and the CLI connects to. access.yaml says which of this, --port and port wins. |
KRAFT_NO_UPDATE_CHECK | unset | Any value turns off the release check in kraft admin start, in kraft admin doctor and in the web UI. See below. |
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. The board's Default editor (editor in theme.yaml) wins over it. |
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 web UI Kraft ships | 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 :. The end-to-end tests use it. |
KRAFT_NO_UPDATE_CHECK
With it set, the web UI no longer checks on every page load. It shows only the result of a check you ran yourself: the About page's Check now or kraft admin update.
Passed to workers
A worker's environment is built from an allowlist, not inherited from the shell that started the server. The variables below are the allowlist and the ones Kraft adds at launch. Any other variable the server has is not passed on, unless the repo adds it.
A worker's own kraft command and MCP client read the variables below. A sandboxed worker gets only what Sandboxed workers lists.
Set by Kraft for each session
| 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. See KRAFT_WORK_ITEM_ID. |
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_WORK_ITEM_ID
The CLI and MCP server refuse a worker's decisions about its own item (see MCP tools). KRAFT_WORK_ITEM_ID is not set for an escalation turn, which runs as a person's session.
Copied from the server's environment
Kraft copies each of these into a worker's environment when the server has it, and leaves it unset when the server does not.
| Group | Variables |
|---|---|
| Running a process | PATH, HOME, USER, LOGNAME, SHELL, LANG, LC_ALL, TERM, TZ, TMPDIR, SSH_AUTH_SOCK |
| Proxy | HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY, and the same four in lower case |
| CA certificates | SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, NODE_EXTRA_CA_CERTS |
| Locating this instance | KRAFT_HOME, KRAFT_RUN_DIR, KRAFT_CONFIG_DIR, KRAFT_TEMPLATES_DIR, KRAFT_SKILLS_DIR, KRAFT_HOST, KRAFT_PORT, so the worker's kraft command reaches the instance that started it |
| Server pid and port | KRAFT_DAEMON_PID and KRAFT_DAEMON_PORT. The names say daemon; the process is the Kraft server. A worker uses them to tell the server apart from a stray process before it kills anything on a port. |
| Claude Code's credentials | ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN. See Other variables. |
Set at launch
Kraft adds these to the launch that needs them.
| Variable | Set when | What it does |
|---|---|---|
GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL | Every launch | The identity a worker commits under: the server's own values where it has them, else user.name and user.email from the repo's git config. A repo's env outranks it in a sandbox. |
CURSOR_CONFIG_DIR | A cursor harness launch | A config directory Kraft owns for the run, so your own Cursor config is not read or touched. |
OPENCODE_CONFIG_CONTENT | An opencode launch whose policy has tool rules | The permission block that enforces allowed_tools and deny_tools. |
PYTHONDONTWRITEBYTECODE | A subprocess or test command | 1, so a fix loop's re-run tests never import stale bytecode. |
HTTP_PROXY, HTTPS_PROXY, NO_PROXY, their lower-case forms and NODE_USE_ENV_PROXY | A sandboxed launch under network: | Point the worker at Kraft's proxy and nowhere else. See Network policy. |
A sandboxed container may carry more than this list; Sandboxed workers says what reaches it.
Added by the repo
A repo's env and env_passthrough add to this list; how to set them is in the env field of repos.yaml.
Any other KRAFT_* variable the server has stays behind: set it in env, or name it in env_passthrough. So does another agent's API key, such as CODEX_API_KEY, unless you name it in env_passthrough.
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, unless the repo's sandbox credentials lists the name: then a sandboxed worker gets a sentinel and the egress proxy adds the real value. |
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. |
Kraft does not read EDITOR or VISUAL.
Related
- repos.yaml: the
envandenv_passthroughfields a repo uses to add to a worker's environment. - Sandboxed workers: what reaches a sandboxed worker instead.
- Run Kraft as a service: the variables a service unit copies.