kian

Apache-2.0 · Open source · Self-hostable

Sessions die.
The work doesn’t.

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.

  • Model-neutral
  • Bring your own machine
  • Bring your own loop
session 9f3c2a1e completed
  1. 1session/created
  2. 2drain/claimedepoch 1 · kian-serve
  3. 3input/admitteduser
  4. 6step/requestdeepseek-flash
  5. 7assistant/message
  6. 9session/endedcompleted
The exact request bytes are persisted before the call flies — replay is byte-identical.
Embedded sqlite No external queue Append-only events OpenAI-compatible One process

The problem

A single-session agent has one structural point of failure.

Not incidental — structural. Each property below follows from one design decision: the conversation is the process.

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.

It cannot be redirected

Steering or interrupting mid-turn has no defined boundary, so a new instruction either gets ignored or corrupts the turn it lands in.

It cannot be audited

“The agent said it was done” is not evidence. Without a durable record there is nothing to replay, export or diff.

It leaks cost silently

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

Three properties separate a runtime from an agent framework.

Work that survives the process, machines you choose, and the loop you already run.

01

Durable execution

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.

step/request persisted before the call flies

02

BYOM execution

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.

Offline work parks and resumes honestly

03

Harness integration

The built-in ReAct loop, or dsh / Claude Code / Codex behind the same LoopDriver seam and the same event kinds, selected per worker agent.

Projection-only sessions, with a stated capability matrix

The boundaries

What it does not promise.

Durability has edges, and they are contract — stated in the spec and the capability matrix, not discovered in production.

No cross-worker failover

A worker binding is immutable. Moving machines means a new session, not a silent migration.

No exactly-once commands

The queue is at-least-once and results dedupe on command id — replay is safe, not magic.

No byte-level replay for projection-only harnesses

If Kian cannot see the request bytes, it will not claim that it can.

The model

Five sentences define the system.

Execution is an interval that can be claimed, lost and reclaimed. Nothing that matters lives only in memory.

  1. Admitdurable inbox row first
  2. Wakeadvisory signal
  3. Drainclaim · epoch + lease
  4. Promoteinputs become context
  1. A session is the one first-class durable entity.Turns, threads and endpoints derive from it.
  2. The event stream is the sole truth.Append-only, never rewritten; state is a projection of it.
  3. An input becomes durable before any wake fires.Wakes are advisory and may fold or be lost; the inbox is the real queue.
  4. A drain is the execution hold interval.Claim, consume what is eligible, promote at safe boundaries, exit. It has no durable identity.
  5. The agent loop is control flow inside a drain.The core holds and persists execution; the loop decides what to do with it.

The audit record

The stream is 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.

events · SSE
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

Read it, replay it, export it.

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

kill -9 mid-turn. Restart. The work continues.

The failure mode is the demo: kill the process while the provider call is in flight, then restart on the same sqlite file.

before restart
$ 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.

after restart
$ 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

One binary. One sqlite file. No external queue.

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.

  1. 1Install

    curl -fsSL https://github.com/flyer103/kian/releases/latest/download/kian-aarch64-apple-darwin.tar.gz \
      | tar -xz -C /usr/local/bin kian kiand
  2. 2Write kian.yaml

    listen: "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
  3. 3Serve

    export DEEPSEEK_API_KEY=sk-...
    kian serve --config kian.yaml
  4. 4Run a session

    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.

Read the README