Skip to content
agentsessions

Durable agent sessions Run it once. Replay it exactly.

Your agent does not call the model. The host does, and records the answer. That one inversion is why a run here can be replayed byte-for-byte, forked for nothing, and checked by someone who does not trust you.
QuickstartRead the docsGitHub
local · no server, no API keyprovider calls 0
$agentctl exec --input "hello world"session sess-6ff29e8d93d3a4c65f6f38bcseq=1   EVENT_INPUT  user: hello worldcalling providerseq=2   EVENT_MODEL_CALLseq=3   EVENT_OUTPUT  assistant: echo:hello worldseq=4   EVENT_ENDone turn, journaled and hash-chained
$agentctl replay --session sess-6ff29e8dseq=1   EVENT_INPUT  user: hello worldseq=2   EVENT_MODEL_CALLseq=3   EVENT_OUTPUT  assistant: echo:hello worldseq=4   EVENT_ENDbyte-identical, and the provider was never called

The inversion

Section titled “The inversion”

Nearly every agent framework lets the agent call the provider. The completion then exists only in the agent’s memory, so the log can describe what happened but never rebuild it. Re-running is the best on offer, and a re-run drifts.

Here the host performs the call on the harness’s behalf. The completion passes through the host on its way back and lands in the journal as a record. Look for the arrow to the provider: it leaves the host, and the sandbox has none.

1 / 7one turn, across process boundaries
A turn flowing from your application into the agentsessions host, which provisions a sandbox through the Runtime SPI and drives a harness inside it, while the host itself makes the model call and appends the result to the journal. YOUR APPLICATIONAGENTSESSIONS HOSTSANDBOXhost makes the callappendcreate / restoreharness stream, bidirectionalclient / SDKSessions APIPlacerControllerModel providerJournalRuntimeHarness
Your application calls Exec, and records stream back as they commit.

What that buys

Section titled “What that buys”

Replay costs nothing

Recorded completions are served from the log, so reconstruction is the same bytes rather than a similar answer. Zero provider calls, enforced in the controller and covered in CI.

Fork is not a re-run

Children inherit the parent’s prefix and diverge independently, so a fan-out starts from identical state at no model cost.

Placement is checked first

A harness declares what it needs to survive a resume and a runtime declares what it offers. Impossible pairings are refused before compute is provisioned, so the system degrades honestly instead of resuming wrong.

execcompute LIVE
A session log growing by four records, being replayed, forked into a child, then suspended and resumed. 1INPUT2MODEL_CALL3OUTPUT4END5resumed5LIFECYCLE6child turnsessionfork
Each turn appends typed, hash-chained records to one append-only log.

Everything it does, on a real cluster

Section titled “Everything it does, on a real cluster”

A plain Deployment and a PersistentVolume: no substrate, no memory snapshot. A turn, a second turn, a free replay, a two-way fork, suspend and resume, then the pod is deleted and a different pod picks the session up mid-conversation.

kind cluster — the full lifecycle, then pod deathrecorded
Recorded by hack/demos/kubernetes-tour.sh against deploy/kubernetes/agentsessionsd.yaml. Nothing is staged: the replay after the pod dies is served from the journal, so the model is called zero times.

Build on it

Section titled “Build on it”

Three contracts. One neutral wire form with a Go SPI, and Event is shared by the log and the harness stream, so what is journaled is exactly what the harness emitted.

Sessions

CreateSession   Exec      Fork
GetSession      Replay    Suspend
ListSessions              Resume

Harness

Describe  the static contract
Run       drive one turn,
          emitting typed events

Runtime

Create    Restore   Stop
Snapshot  Fork      Status
          Capabilities

Three runtimes ship. runtime/local is filesystem-only and refuses a memory-snapshot harness rather than resuming it wrongly. runtime/remote attaches to a harness you are already running, so your agent is registered by address rather than compiled into the server. runtime/substrate runs both capability tiers against a real cluster on every pull request, both on a micro-VM. Kata, Cloud Hypervisor, and plain pods fit the same SPI. No provider SDK appears anywhere, and CI asserts the core links no backend vendor.

Terminal window
go install github.com/aramase/agentsessions/cmd/agentctl@latest

Signed archives and container images are on the latest release.

Keep reading

Section titled “Keep reading”
QuickstartRun the loop yourself in a few minutes.
ConceptsSessions, typed events, incarnations, fences, resumability, capabilities.
How you use itWhich seam to build against, and what each seam is for.
Writing a harnessImplement Describe and Run; durability is not yours to build.
ArchitectureThe host, the log, placement, and how the pieces fit.
Running on agent-substrateBoth tiers on a real cluster, on a micro-VM.
ObservabilityStructured logs, request correlation, and what to watch.
Security postureWhat is and is not protected today. Read before exposing a host.
API referenceGenerated from the proto: every message, field, and RPC.
FAQWhy not just a transcript, why fencing, and other recurring questions.