Starting and reaching Kraft

Start here when the kraft command or the server itself is the problem.

kraft: command not found

Your shell prints kraft: command not found (zsh: command not found: kraft) when the directory kraft was installed in is not on your PATH. That is usual right after a uv install, the install script included.

1. Run uv tool update-shell, or add the directory kraft is in to PATH yourself.
2. Open a new terminal.
3. Check that the command is found:

   kraft --version
   

You know it worked when kraft --version prints kraft X.Y.Z.

After a Homebrew install, put $(brew --prefix)/bin on your PATH instead.

If Kraft runs as a service, also read The kraft on PATH doctor row.

The kraft on PATH doctor row

This is also where to look when a service cannot find kraft.

kraft admin doctor fails its kraft on PATH row with not on PATH when the kraft command is not on PATH, usually right after a uv install. The plugin, every MCP registration and the hooks run kraft by name, so with no kraft on PATH they start nothing.

Fix PATH as in kraft: command not found, then start kraft again from a new terminal.

A service keeps the PATH it was installed with, which is also what finds the agent CLI the agent: <profile> row checks. Reinstall it from the new terminal you started kraft from, a shell where kraft and the agent CLI both run:

kraft admin uninstall-service
kraft admin install-service

Kraft won't start: port already in use

If something already answers on Kraft's port (8765 by default), kraft refuses to start and says what it found:

kraft: refusing to start - something is already answering on 127.0.0.1:8765. curl http://127.0.0.1:8765/api/health to inspect it, or `kraft admin stop` if it's yours.

When it names a Kraft server instead of "something", that is an instance you already started: kraft admin stop stops it.

Otherwise pick another port. kraft admin start --port 9000 moves only the server. To have the kraft command, the plugin and the VS Code extension follow it, set port in access.yaml instead.

A webhook or proxy gets 403 "unexpected Host"

{"detail":"unexpected Host for a server bound to 127.0.0.1"}

On a loopback bind (the default), Kraft answers only a request addressed to localhost, 127.0.0.1 or [::1]. A webhook to POST /api/triggers, a health check to GET /api/health, and anything else that reaches Kraft through a tunnel or reverse proxy with the name its client used, gets this 403. Adding the name to allowed_hosts changes nothing: it is not read on a loopback bind.

Fix it one of two ways:

• For the board, webhooks and scripts: bind Kraft beyond loopback, with a password, and list the name the proxy's clients use in allowed_hosts. Remote access has the steps.
• For webhooks and scripts alone: make the proxy send Host: localhost. A loopback-bound Kraft asks a request from this machine for no password, so read Put a proxy in front of Kraft before you do.

Who may call lists which callers need which credentials, and when each gets a 403.

Related

• Doctor failures: the kraft on PATH row and every other kraft admin doctor check.
• Remote access: binding beyond loopback, and a proxy in front of Kraft.
• Install: installing Kraft and checking the install.