Server lifecycle

The local capa server (default 127.0.0.1:5912, set by server.host / server.port in ~/.capa/settings.json) handles credentials, MCP proxying, and capa sh tool execution. capa install usually starts it for you; use these commands to manage it explicitly.

Synopsis

capa start [-f|--foreground]
capa stop
capa restart
capa status

Commands and flags

Command	Flags	Description
`start`	`-f`, `--foreground`	Start the server in the background, or in the foreground for debugging
`stop`	None	Stop the capa server and any active `capa wrap` sessions
`restart`	None	Restart the capa server
`status`	None	Check server health and uptime, and show the active secret storage tier (Credentials)

Examples

capa start
capa start -f
capa status
capa restart
capa stop

After changing server commands, env vars, or options.toolExposure, restart so the proxy picks up the new config:

capa install
capa restart

Local API security

The server’s HTTP API (/api/*) requires a bearer token, even on loopback. The capa CLI and the web UI it opens send the token automatically, so normal use needs no setup.

Setting	Behavior
`~/.capa/auth.token`	Created on first server start, readable only by your user. Scripts calling `/api/*` directly must send `Authorization: Bearer <token>` (not a query string)
`CAPA_AUTH_TOKEN`	Environment override for the token, used instead of the file
`CAPA_ALLOWED_ORIGINS`	Comma-separated extra browser origins allowed to call the MCP endpoint. The server’s own `localhost` / `127.0.0.1` / `[::1]` origins are always allowed

Other guards apply automatically:

Requests whose Host header is not a loopback name or the configured bind host on the server port are rejected with 421 Misdirected Request. This blocks DNS-rebinding attacks; reach the server as localhost or 127.0.0.1, not through a custom hostname.
State-changing API requests from another site are rejected (403), and must use a JSON or multipart content type.
The MCP endpoint needs no token while the server is bound to loopback. If you bind server.host to a non-loopback address, the server prints the token at startup and every client must send it on both /api/* and the MCP route.