Operating the server

One server owns everything: the SQLite store, the providers, the ribs, the browser UI, and an MCP endpoint for other agents, all on port 7878. Here is how to run it, check it, and stop it cleanly.

Start it

keelson start launches the server in the background and returns once it is listening, then reports the URL. It re-launches the server as a detached process that outlives the terminal.

keelson start

Open http://127.0.0.1:7878 and you get the full UI from the same port as the API: Chat, Workflows, Memory, and a tab for each installed rib.

Add --foreground (-f) to run it attached instead. It builds the database, ribs, and routes, installs graceful-shutdown handlers, and stays on the terminal until you press Ctrl-C, with the boot log in front of you.

keelson start --foreground

keelson server listening on http://127.0.0.1:7878/

The former keelson service group (and its serve alias) still works as a hidden, deprecated alias; prefer the top-level start / stop / status.

Running offline

Real agents need a Copilot subscription or an Anthropic API key. With no keys, start with KEELSON_PROVIDERS=stub for the offline echo provider, which is enough to exercise the harness, the workflow engine, and your ribs’ wiring without credentials.

Check it

keelson status reports whether the server is running and where, and cleans up a stale record if it finds one. The exit code is scriptable: 0 when the server is up, 3 when it is down.

keelson status

For a full health sweep, keelson doctor probes six categories in one pass: toolchain, server, database, auth, workflows, and ribs. Every check that fails or warns carries a hint naming the next command, so doctor is the first thing to run whenever the harness behaves unexpectedly.

keelson doctor          # add --strict to exit non-zero on warnings too

Stop it

keelson stop

Stop drains in-flight runs, closes the database, and exits, falling back to a signal only if the graceful path does not land. It is safe to run when nothing is up: it reports not running and cleans any stale state.

Restart it

keelson restart

Restart stops the running server (the same graceful-then-signal path as stop) and starts a fresh background server, reporting its URL. If nothing is running it just starts one. A stop that genuinely fails (a stale record, an unmanaged server holding the port) aborts the restart rather than launching a second server alongside it.

The MCP endpoint

The same server speaks the Model Context Protocol at /api/mcp, so other agents (Claude Code, Cursor, the Codex CLI) can call your ribs’ tools. It mounts automatically with the server and, on loopback with no token, exposes the full tool registry by default, state-changing tools included (exposeStateChanging: false restricts it to read-only). keelson status reports its URL when it is mounted.

Tune what crosses, or gate it behind a token, in the mcp config block. The Using keelson over MCP guide walks a client through connecting, and Configuration documents every knob.

Where the state lives

Path	What
~/.keelson/keelson.db	The SQLite store: conversations, runs, node outputs, memory.
~/.keelson/server.json	The running server’s record: its URL, pid, version, shutdown token, and (when MCP token-gating is on) the MCP token.
~/.keelson/	The managed home overall, including workflows/ and installed ribs.

KEELSON_HOME relocates the whole home; see Configuration for that and the other KEELSON_* variables.

Local-only, by wiring

The server binds to 127.0.0.1, and state-changing endpoints are gated to loopback origins. The background server’s shutdown endpoint is gated by a token written into server.json, so only a caller that can read your disk can stop it.

Related

• The CLI: the full command tree and the exit-code contract.
• Your first run: install, the health sweep, and a first chat turn, walked end to end.
• Configuration: the providers and KEELSON_* variables the server reads at boot.