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 addon validate PATH
kraft admin addon collection add SOURCE [--ref REF] [--auto-update]
kraft admin addon collection list
kraft admin addon collection update [NAME]
kraft admin addon collection auto-update NAME on|off
kraft admin addon collection remove NAME
kraft admin addon install ADDON@COLLECTION [--as ALIAS] [--auto-update] [--re-install] [-y]
kraft admin addon update [ADDON@COLLECTION ...] [-y | --check]
kraft admin addon auto-update ADDON@COLLECTION on|off
kraft admin addon enable ADDON@COLLECTION
kraft admin addon disable ADDON@COLLECTION
kraft admin addon uninstall ADDON@COLLECTION
kraft admin addon list
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.

Before it installs a release of another major version, it lists each loaded Kraft add-on whose requires.kraft that release does not meet, and asks Install it anyway? [y/N]. Those add-ons stop loading until each publishes a version for the new major. Answering no, or running with no terminal, installs nothing and exits 1.

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.

It also rereads addons.yaml and addons.lock, and restores in the background any add-on store the lock names and this machine lacks. An add-on file that does not read is refused, and the server keeps the add-ons it has. See What loads.

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.
• storage shows worktree usage against storage.worktrees.limit, and appears only when a limit is set. held makes the status degraded, so the command exits 1. With auto_cleanup set, the line also says how many finished items ended too recently to clean up.
• 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. With storage.worktrees.limit set, a storage row says how much the worktrees use of the limit: ok under the quota, warn over it, and over the limit a failing health row. 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 25 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.

Install and update add-ons

Add a collection and install from it

kraft admin addon collection add SOURCE records a collection in addons.yaml under the name its collection.json declares. owner/repo is written as its full GitHub URL. kraft admin addon install ADDON@COLLECTION then fetches the add-on, checks it against this instance, and prints a review: what can change how far a run reaches first, then the rest. Nothing is installed until you accept it. -y accepts without asking; with no terminal and no -y the install is declined.

--as ALIAS installs the add-on under another namespace. --re-install takes the commit the collection's ref names now, even when the add-on's version has not changed.

Update add-ons

kraft admin addon update reviews every installed add-on that has an update, one at a time: its version changed (its files, for a directory collection), or you changed its alias, ref or collection URL by hand. An add-on that fails a check is reported and the others go on. A change that would break one of your own chains, a default_chain in repos.yaml or an intake.yaml schedule is refused and names the reference.

--check prints the reviews and changes nothing. It exits 0 when every add-on is current, 1 when an update is waiting, 2 when an update would be refused and 3 when it could not check, so a scheduled job can tell them apart.

An add-on set to auto-update is checked after each server start and once a day while the server runs. kraft admin addon list marks it auto-update (collection) or auto-update (addon); its last outcome is on the add-on updates row of kraft admin doctor and in GET /api/health. See Auto-update.

Remove an add-on

kraft admin addon uninstall and disable are refused while your library, a chain, repos.yaml, intake.yaml, policy.yaml or harnesses.yaml still names the add-on's namespace. The refusal lists each reference.

A worker cannot run the verbs that change add-ons.

Check an add-on

Validate a collection or an add-on

kraft admin addon validate PATH checks a collection or a single add-on directory and installs nothing. PATH is a directory holding .kraft/collection.json, or one holding .kraft/addon.json.

It checks each add-on's files against the size and content limits, both manifests, the Kraft version the add-on requires, and that every chain the add-on ships resolves.

When the config directory holds a library.yaml, it also checks the add-on as an install into that instance: its requires.harnesses and requires.profiles, its namespace, and your own chains. With none, it prints a skipped: line naming those checks.

It prints one line per add-on with its version and digest, then each problem with its file, then warnings: a manifest key Kraft does not read, and a file that looks like part of the add-on layout and is not.

It exits 0 when every add-on passes and 1 otherwise, so a collection's CI can run it on every push; Run validate in CI shows a job. --json prints the report as an object with addons, problems, warnings and skipped.

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.
• Share chains with add-ons: publish a collection and install an add-on from it.
• Add-ons and collections: the manifests, addons.yaml, the lock, and when an add-on loads or updates.