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.
Run serve
Section titled “Run serve”kora serve # or: kora --dev serve -y (dev profile + auto-approve tools)# serving on /Users/you/.kora/serve.sock — stays in the foregroundStop with Ctrl+C: the socket and all *.attach.json liveness files are removed.
attach
Section titled “attach”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.
Writer and viewers
Section titled “Writer and viewers”- One writer per session. A second
attach(orwrite:true) getssession writer slot held, exit 3. - Any number of viewers: a raw client (
nc -U <profile>/serve.sock) can sendattachwith"write":falseand 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.
Wire ops
Section titled “Wire ops”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 |
Liveness
Section titled “Liveness”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.
Security
Section titled “Security”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).
Troubleshooting
Section titled “Troubleshooting”kora: no serve on this profile(exit 2) →kora serveisn’t running, or the--devflag 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 servewas 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/providerinkora chatfirst. - Stale
serve.sockafter a crash →servetolerates and replaces one stale socket on startup; a second stale file means a server may still be running — checkpgrep -f "kora serve".