It dies with its process
A crash, a deploy or an OOM loses the work in flight, and there is no record of what was sent, what was answered, or which tools ran.
Apache-2.0 · Open source · Self-hostable
Kian is a durable execution runtime for agents. It makes the session the durable entity and the event stream the only truth — so a crash, a deploy or a machine move costs a restart, not the work.
9f3c2a1e
completed
The problem
Not incidental — structural. Each property below follows from one design decision: the conversation is the process.
A crash, a deploy or an OOM loses the work in flight, and there is no record of what was sent, what was answered, or which tools ran.
Steering or interrupting mid-turn has no defined boundary, so a new instruction either gets ignored or corrupts the turn it lands in.
“The agent said it was done” is not evidence. Without a durable record there is nothing to replay, export or diff.
Every rewrite of earlier context invalidates the provider’s prefix cache, so the same tokens are paid for again and again, invisibly.
What it guarantees
Work that survives the process, machines you choose, and the loop you already run.
A crash, deploy or machine move costs a restart, not the work. Session state is a projection of an append-only stream, and a new drain replays that stream and continues.
A single-binary kiand daemon runs the session’s commands on the box you pick, over a durable at-least-once queue, bound 1:1 to its worker session for that session’s whole life.
The built-in ReAct loop, or dsh / Claude Code / Codex behind the same LoopDriver seam and the same event kinds, selected per worker agent.
The boundaries
Durability has edges, and they are contract — stated in the spec and the capability matrix, not discovered in production.
A worker binding is immutable. Moving machines means a new session, not a silent migration.
The queue is at-least-once and results dedupe on command id — replay is safe, not magic.
If Kian cannot see the request bytes, it will not claim that it can.
The model
Execution is an interval that can be claimed, lost and reclaimed. Nothing that matters lives only in memory.
The audit record
Read state back from the projection, never from a column. Replay re-derives the same bytes. Export writes a JSONL audit package.
event: kian
data: {"seq":1,…,"kind":"session/created","bytes":{},"version":0}
data: {"seq":2,…,"epoch":1,"kind":"drain/claimed","bytes":{"epoch":1,"holder":"kian-serve"}}
data: {"seq":3,…,"kind":"input/admitted","bytes":{"content":"hello kian","role":"user"}}
data: {"seq":6,…,"kind":"step/request","bytes":{"body":{…},"iteration":0,"model":"deepseek-flash"}}
data: {"seq":7,…,"kind":"assistant/message","bytes":{"content":{"text":"…"},"role":"assistant"}}
data: {"seq":9,…,"kind":"session/ended","reason":"completed","bytes":{}}
event: done
data: ended
Abridged capture against a scripted provider, ids shortened. The stream is the evidence, not the summary.
$ kian session inspect "$SID" --config kian.yaml
$ kian session replay "$SID" --config kian.yaml
$ kian session export "$SID" --config kian.yaml --out audit.jsonl
$ kian cache-stats --config kian.yaml --json
Proof, not promises
The failure mode is the demo: kill the process while the provider call is in flight, then restart on the same sqlite file.
$ kill -9 <pid of kian serve>
state running
requests 1
assistant messages 0
The request bytes are durable; the turn is not finished. No end write happened, so the session is detectable as recoverable.
$ kian serve --config kian.yaml
state completed
events 12 (next seq 13, epoch 2)
drain claims 2
The takeover rewrites no earlier event: the stream shows drain/claimed epoch 2, and the retried request derives a byte-identical prefix.
Abridged output from the README walkthrough. The automated version runs six kill points across repeated iterations in crates/kian-cli/tests/chaos_recovery.rs.
Quickstart
No toolchain needed for the container or the prebuilt binary; the source path needs Rust 1.85+. The provider contract is base_url + OpenAI chat-completions + SSE, so any compatible endpoint works unchanged.
curl -fsSL https://github.com/flyer103/kian/releases/latest/download/kian-aarch64-apple-darwin.tar.gz \
| tar -xz -C /usr/local/bin kian kiand
kian.yamllisten: "127.0.0.1:7433"
storage:
sqlite: "./kian.db"
agent:
id: my-agent
model_slots:
main: {provider: deepseek, model: deepseek-flash}
providers:
deepseek:
base_url: "https://api.deepseek.com"
api_key_env: DEEPSEEK_API_KEY
drain:
max_iterations: 32
recovery:
rules:
- class: rate_limited
action: {backoff_retry: {delay_ms: 500}}
- class: unknown
action: fail
export DEEPSEEK_API_KEY=sk-...
kian serve --config kian.yaml
SID=$(curl -s localhost:7433/rpc -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"create_session"}' | jq -r .result.session)
curl -s localhost:7433/rpc -H 'content-type: application/json' \
-d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"submit\",\"params\":{\"session\":\"$SID\",\"content\":\"hello kian\"}}"
curl -sN localhost:7433/sessions/$SID/events # live SSE, ends after session/ended
Full walkthrough, including the kill -9 proof, projection read-back and test suites.