Skip to content

serve & attach

kora serve runs a foreground control plane on <profile>/serve.sock (Unix socket, JSONL v1). It owns the whole profile’s session registry: every session — including ones created by Kora Desktop — can be driven through it. kora attach connects a terminal as the session’s writer.

Terminal window
kora serve # or: kora --dev serve -y (dev profile + auto-approve tools)
# serving on /Users/you/.kora/serve.sock — stays in the foreground

Stop with Ctrl+C: the socket and all *.attach.json liveness files are removed.

Terminal window
kora attach <session_id>
# kora: attached to session-… (ctrl+d to detach)

Write a prompt, press Enter — answer text streams on stdout, tool/chrome lines on stderr. On needs approval, the next line you type is y, n or always. Ctrl+D detaches cleanly.

  • One writer per session. A second attach (or write:true) gets session writer slot held, exit 3.
  • Any number of viewers: a raw client (nc -U <profile>/serve.sock) can send attach with "write":false and receives the event stream read-only.
  • Writer disconnect cancels the in-flight turn and releases the slot; viewer disconnect only unsubscribes; slow consumers are dropped.

Same JSONL protocol as headless JSON, plus:

Op data Returns
attach {sessionId, write} writer or viewer subscription
detach {sessionId} release the subscription
sessions {} {sessions:[{id,title,provider,model,folders,busy,writer,viewers}]}
new {cwd?} {sessionId} — cwd defaults to the serve process cwd
prompt {sessionId, text} queued turn
steer {sessionId, text} mid-turn steering
cancel {sessionId} abort in-flight turn
approve {sessionId, id, decision} allow/always/deny
answer {sessionId, id, value} answer user-input request
kill {sessionId} drop every attachment of a live session — viewers get session-killed, the writer’s turn is cancelled, single-subscription conns close; errors if the session is not hosted
shutdown {} stop the server

While a client is attached, <id>.attach.json marks the session live: kora sessions --json shows "live":true and kora sessions / TUI pickers show ● live. Liveness is verified against PID and socket — the file is advisory, never the source of truth.

The socket has no authentication: any process that can open <profile>/serve.sock can drive your sessions. The profile directory is created 0700, so on a normal setup only your user can reach it — do not loosen that. Unix only (macOS/Linux); remote access goes through SSH (ssh -L can forward the socket).

  • kora: no serve on this profile (exit 2) → kora serve isn’t running, or the --dev flag mismatches between commands.
  • session writer slot held (exit 3) → another client holds the writer slot; detach it or attach read-only.
  • attach dies with exit 4 → kora serve was stopped or crashed; restart it and re-attach.
  • Session fails immediately with provider ... not found → the session points at a provider configured in another app/profile; pick a session created by the CLI or set /provider in kora chat first.
  • Stale serve.sock after a crash → serve tolerates and replaces one stale socket on startup; a second stale file means a server may still be running — check pgrep -f "kora serve".