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
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
| Command | Effect |
|---|---|
start | Runs the server in the foreground; the same as bare kraft. --host and --port override KRAFT_HOST and KRAFT_PORT, which override access.yaml. The flags are not saved: other commands still dial the host and port in KRAFT_HOST/KRAFT_PORT or access.yaml, so start prints the KRAFT_HOST=H or KRAFT_PORT=N they need when --host or --port differs (a wildcard --host such as 0.0.0.0 needs none). --detach/-d forks it into its own session and returns once it is up. |
stop | Sends SIGTERM to the process in run/kraft.pid. |
restart | Stops, then starts again the same way it was running: through the service manager if one is installed, back into the background if it was detached. A server running attached to a terminal is stopped, with a note that only that terminal can bring it back. |
health | Exits 1 when the server is degraded, with the reasons on stdout. |
doctor | Runs every check in one pass. Exits 1 if any fails. |
reindex | Rescans documents into the search index. --repo limits it to one repo. |
reload | Rereads the template library and policy.yaml from disk, with no restart. |
update | Installs the newest release, or runs brew upgrade if you installed with Homebrew. --force installs even when current. --restart also restarts a running server. --channel rc|beta|alpha takes pre-releases (rc only release candidates and finals, beta adds betas, alpha takes anything); the default, stable, never does, and Homebrew installs only track stable. -y accepts the template migration without asking. |
install-service, uninstall-service | Register or remove Kraft as an OS service (a launchd agent on macOS, a systemd user unit on Linux) that restarts if it exits. Stop a running server first. |
templates lint | Checks every chain in the library, including that harnesses.yaml can launch each agent task (a profile: with no model for its harness's provider is an error), and 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. |
templates show ID | One chain as written. --resolved expands its library components. |
templates library [ID] | Every library component, its kind and the chains using it. With an ID, one component's definition, users and lint issues (tasks.implementer, or a unique bare name). |
harnesses [ID] | Every harnesses.yaml profile, its provider, and the library tasks and chains selecting it (a chain's own harness: on a task included). With an ID, one profile in detail. |
init [--repo] | Registers the MCP server and skills with an agent. --repo installs into this repo, not your user config. See Agent integration. |
mcp | Serves the MCP tools over stdio. |
permission-hook HARNESS | What a Cursor or Codex worker's pre-tool hook runs. You do not run it by hand. --fail-closed denies rather than giving no opinion when Kraft cannot answer. See Permission gate. |
Kraft refuses to start on a non-loopback address without a password. It also
refuses a second start against the same run directory while the first is
alive. The foreground server stops on Ctrl-C. Use kraft admin stop for one
you started elsewhere.
kraft admin doctor fails its kraft on PATH row when an older kraft sits
ahead of this one on PATH, and kraft admin update warns about it. Its
embeddings row fails when an installed embedder's model will not load. See
Enable vector search.
A sandboxed repository's sandbox row names the runtime it found (Docker or
Podman, rootless or not) and the resource limits it can enforce, and fails
when that runtime does not answer, when SELinux enforces and
sandbox.yaml does not say how to get past
it, when ca_bundle cannot be used, when the sandbox sets a
limit the runtime cannot
enforce, or when the sandbox image is not pulled. It reads sandbox.yaml
afresh each run. A proxy row warns when a proxy variable points at this
machine's loopback, which a container cannot reach, and a ca row when
SSL_CERT_FILE is set but cannot be used, so sandboxes ignore it. Those two
read doctor's own environment, not the daemon's.
For a repository whose sandbox is a Kit,
doctor fetches and lowers the Kit first: the sandbox row fails naming the Kit
and why when it cannot, and otherwise it and the egress, proxy and credentials
rows check the sandbox the Kit lowers to. A kit hosts row warns about each
host a harness requires that the Kit does not allow, and a kit credentials
row about each credential service with no binding in sandbox.yaml. Doctor
fetches each Kit it has not cached; under Podman a single-manifest Kit is
pulled, which can take up to 10 minutes per repository the first time.
Migrating a pre-V1 template configuration
"V1" is the current template format: a library.yaml plus chains/*.yaml. The
older format had a registry.yaml and no library.yaml. A Kraft home that still
holds it is not converted or overwritten. The
server starts degraded and refuses new work until you run
kraft admin update. That command says what will change, asks, and then moves
the whole templates/ directory to a templates.pre-v1-<time> backup beside
it and installs the V1 configuration.
-yaccepts without the question. With no terminal and no-y, it changes nothing.access.yaml,notify.yaml,theme.yaml,repos.yaml,intake.yaml,steering/andharnesses/carry across. The next start foldssteering/*.mdintolibrary.yamlas steering profiles.policy.yamlstarts from the V1 default and keeps your value for every key V1 still has. Kraft prints each key it drops, with its old value.- Your old chains and registry stay only in the backup. There is no migration helper.
An update interrupted mid-swap is finished by the next start or the next
kraft admin update.