Admin verbs

kraft admin runs this machine's Kraft server. Bare kraft is the same as kraft admin start.

kraft admin start --port 9000
kraft admin start --detach
kraft admin stop
kraft admin restart -y
kraft admin health
kraft admin doctor
kraft admin reindex --repo <path>
kraft admin reload
kraft admin update --restart -y
kraft admin install-service
kraft admin uninstall-service
kraft admin templates lint
kraft admin templates lint --dir PATH
kraft admin templates show ID
kraft admin templates show ID --resolved
kraft admin templates library
kraft admin templates library ID
kraft admin harnesses
kraft admin harnesses ID
kraft admin init --repo
kraft admin mcp
kraft admin permission-hook cursor --fail-closed

Run the server

Start the server

Kraft refuses to start when:

• the address is not loopback and no password is set;
• a server is already running against the same run directory.

The foreground server stops on Ctrl-C. Use kraft admin stop for one you started elsewhere.

The flags are not saved: other commands still dial the host and port in KRAFT_HOST and KRAFT_PORT, or in access.yaml. When --host or --port differs from that value, start prints the KRAFT_HOST=H or KRAFT_PORT=N line they need. A wildcard --host such as 0.0.0.0 needs none.

With --detach, if the server exits instead, start prints the error (such as RuntimeError: database schema vN is newer than code vM), the end of that start's output, and the path of server.log.

Stop the server

kraft admin stop sends SIGTERM to the process in run/kraft.pid, once it has checked that the process is this Kraft server. Stopping ends every running agent. When Kraft starts again, each of those items stops with a reattach: failure and shows as failed; it does not resume by itself. Pause running items first (see A restart ends running agents).

• A pidfile naming any other process is stale: stop removes it, says so, and signals nothing.
• It lists the active items first, without asking. A server that does not list them within 2 seconds is stopped anyway.
• A repo's setup command that is running is ended too, with everything it started, so it never runs beside the next server's own run of it. A server that is killed (SIGKILL) cannot end it.

Restart the server

kraft admin restart stops the server, then starts it again the way it was running: through the service manager if one is installed, back into the background if it was detached.

Like stop, restart ends any running agent: pause running items first, and retry any item it stopped. It lists the active items first and, in a terminal, asks before going on. -y skips the question.

Update and reload

Update Kraft

kraft admin update installs the newest release with uv, keeping the vector extra and the Python it runs on, or runs brew upgrade if you installed with Homebrew. On a pipx or pip install, or a source checkout, it installs nothing and prints the command that updates that install.

It warns when another install of kraft sits ahead of this one on PATH, since MCP servers and hooks run the first one.

A Kraft home from 0.x holds a registry.yaml and no library.yaml: the server starts degraded and refuses new work until you run kraft admin update. See Migrating a home from 0.x for what the update changes.

Channels

--channel takes one of four values:

Without --channel, the install follows the channel of the release it is:

Homebrew installs only track stable.

Reload the configuration

kraft admin reload rereads the library, the chains, policy.yaml and intake.yaml. A policy.yaml or intake.yaml that does not load is refused and the running one is kept. Reload names it and exits 1, as it does for a chain that does not resolve.

What health prints

kraft admin health prints the server's state as key value lines, and exits 1 unless status is ok. The line after version and the lines after embeddings appear only when they apply:

• installed names the installed version with restart pending, after an update the server has not restarted for. It is not degraded.
• invalid template, invalid policy and invalid intake name each file that does not load, with the reason.
• index error, reattached and orphaned sessions report the search index and the agent sessions found at startup.

status         ok
version        2.0.0
bind           127.0.0.1
documents      214
repos scanned  3
last scan      4m ago
embeddings     available

--json prints the GET /api/health answer.

What doctor checks

kraft admin doctor runs every check in one pass, one line per check, and exits 1 if any fails. --json prints the rows. kraft admin health checks only the server.

Each line starts with ok, warn, FAIL or skip, then the check's name and what it found. A row about one repository carries its name, such as setup my-repo. The last line counts them.

ok    server            http://127.0.0.1:8765
ok    health            ok
...
ok    restart           the server (pid 4242) runs the installed version (2.0.0)
ok    config            /Users/you/.kraft/config
ok    access.yaml       parses
...
ok    spa bundle        /usr/lib/kraft/_bundled/web
...
ok    repo app          /Users/you/code/app
ok    forge app         github · gh
ok    worktrees         /Users/you/.kraft/run/worktrees

all 24 checks passed

The excerpt cuts the rows marked .... The count is for a running server, the shipped chains with claude on PATH, and one connected repo, app, with its commands declared. It grows with each connected repo and each harness profile the chains select. With no repo connected, a repos none connected row stands in for the repo rows.

Doctor failures lists every row with its fix.

Inspect templates and harnesses

Lint the templates

kraft admin templates lint checks every chain in the library, including that harnesses.yaml can launch each agent task (a task's profile: naming an agent profile with no model for its harness's provider is an error). It exits 1 on any error, printing each as file:line:column: message.

--dir PATH checks that directory in-process, with no server and no $KRAFT_HOME.

Show a chain

kraft admin templates show ID asks the running server. A chain file you just added shows only after admin reload, and --resolved expands the version the server last loaded.

kraft admin templates library ID takes a component id such as tasks.implementer, or a unique bare name. A bare name two sections share is refused with each full id. It prints the component's definition, its users and its lint issues.

Related

• Doctor failures: the fix for each row admin doctor can print.
• Run Kraft as a service: install-service, and keeping the server up across restarts.
• Restart Kraft without ending running agents: what stop and restart do to a running agent, and how to avoid it.
• Upgrade Kraft: when to run admin update, and how to pin a version.