README
¶
Agent Runtime
Agent Runtime is a Go platform for durable, session-based agents. It gives an application a stable public API for versioned Agents and Policies, Sessions, Turns, ordered Events, approvals, artifacts, and governed tools. The runtime keeps orchestration, model access, and sandbox execution behind explicit, reviewable boundaries.
This is self-hosted, open-source software. It is not a hosted managed service, a generic autonomous-agent platform, or a promise that a granted process cannot disclose the authority it was deliberately given.
What is here
- A versioned HTTP API and public Go SDK reference.
- Durable runtime-state and orchestration seams.
- Durable Chat, Workspace Agent, and Research Dossier examples.
- A local Kubernetes Stack with separately declared API, orchestration, model, tool, blob, codec, sandbox-control, and sandbox-host roles.
- Sandbox contracts that fail closed when an advertised isolation capability is unavailable.
Read the public documentation, then use the tutorial and code overview to orient yourself in the repository.
Safety and evidence boundary
The supplied API configuration uses in-memory storage and loopback networking for local exploration. It is not a production deployment configuration. The local unsafe sandbox adapter is useful for development compatibility checks; it is not Firecracker isolation. Firecracker claims require separate, retained Linux/x86_64 KVM evidence.
The project records the distinction between code, local checks, hosted CI, and environment proof. Do not treat a green local command as evidence for a deployment-specific boundary.
Architecture
The public API and SDK own the application contract. Runtime state and orchestration own durable session progress. Model and tool adapters pass through policy, approval, capability-grant, audit, and bounded-output seams. The sandbox control plane and host agent have separate authority; a sandbox adapter may advertise capabilities only when it can enforce them.
For the accepted system view, see the architecture guide, runtime language, and sandbox verified boundaries.
Five-minute local start
Prerequisites: Go 1.26+, and two disposable local bearer strings. This starts only the loopback API; it intentionally does not create a production Stack or claim sandbox isolation.
export AGENT_RUNTIME_ADMIN_TOKEN='replace-with-at-least-16-bytes'
export AGENT_RUNTIME_DEVELOPER_TOKEN='replace-with-at-least-16-bytes'
go run ./cmd/agent-runtime-api --config "$PWD/deploy/runtimeapi/api.example.json"
In another terminal, start the browser example. It listens only on loopback and keeps the runtime bearer token out of the browser:
go run ./examples/durable-chat/cmd/durable-chat \
--mode=web \
--runtime-url=http://127.0.0.1:8088
Stop both processes with Ctrl-C. For the declarative local Stack, its
preflight and its cleanup contract, follow the local Stack guide.
Commands
| Command | Purpose |
|---|---|
just check |
Fast repository gate: generated artifacts, race tests, vet, Linux lint, and ledger structure. |
just docs-check |
Regenerate/check docs, validate routes, and build the production documentation site. |
just generate |
Regenerate checked-in contract artifacts. |
just dev-preflight |
Validate the explicitly allow-listed local Stack context before any Kubernetes writes. |
just dev / just dev-down |
Create or remove one labelled local development Stack. |
just verify |
Final release gate; deliberately remains red until every canonical requirement has valid completed evidence. |
Run just with no arguments to list the complete command surface. See
CONTRIBUTING.md for the direct-main verification and
evidence workflow.
Examples and tutorials
Examples use narrow demo identities and cleanup boundaries. They are not templates for granting broad administrator credentials to application code.
Documentation, support, and contributing
The public docs contain the HTTP and SDK references, operator material, troubleshooting, and documentation publication policy. Questions and contributions should start with CONTRIBUTING.md and AGENTS.md.
Report security-sensitive issues privately to the repository owner rather than including secrets, raw prompts, or exploitable detail in a public issue. The verified-boundaries guide records what the project does and does not currently prove.
License
Licensed under the terms in LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
afk-evidence
command
Command afk-evidence creates and validates bounded direct-main evidence logs.
|
Command afk-evidence creates and validates bounded direct-main evidence logs. |
|
agent-runtime-api
command
|
|
|
agent-spec-backfill-controller
command
Command agent-spec-backfill-controller validates one explicit controller declaration.
|
Command agent-spec-backfill-controller validates one explicit controller declaration. |
|
dev-role
command
Command dev-role is the deliberately minimal local composition image for the API, worker, and codec roles before their product implementations land.
|
Command dev-role is the deliberately minimal local composition image for the API, worker, and codec roles before their product implementations land. |
|
docs-publication-verify
command
docs-publication-verify checks a deployed public documentation site against the checked-in route manifest.
|
docs-publication-verify checks a deployed public documentation site against the checked-in route manifest. |
|
egress-proxy
command
Command egress-proxy runs a finite allowlisted HTTP and HTTPS CONNECT proxy.
|
Command egress-proxy runs a finite allowlisted HTTP and HTTPS CONNECT proxy. |
|
firecracker-direct-preflight
command
Command firecracker-direct-preflight validates an operator-owned Linux/KVM boundary before a direct Firecracker smoke run.
|
Command firecracker-direct-preflight validates an operator-owned Linux/KVM boundary before a direct Firecracker smoke run. |
|
firecracker-e2e
command
Command firecracker-e2e records whether this host can run the protected Linux/KVM lane.
|
Command firecracker-e2e records whether this host can run the protected Linux/KVM lane. |
|
firecracker-fixture-preflight
command
firecracker-fixture-preflight validates a locally assembled candidate through the exact fixture provisioning boundary used by the protected smoke runner.
|
firecracker-fixture-preflight validates a locally assembled candidate through the exact fixture provisioning boundary used by the protected smoke runner. |
|
firecracker-release-preflight
command
firecracker-release-preflight checks the local, reviewable inputs for the one later publication of an M4 fixture release.
|
firecracker-release-preflight checks the local, reviewable inputs for the one later publication of an M4 fixture release. |
|
firecracker-runner-preflight
command
Command firecracker-runner-preflight validates the static bootstrap contract required before a protected Firecracker KVM workflow can mint smoke evidence.
|
Command firecracker-runner-preflight validates the static bootstrap contract required before a protected Firecracker KVM workflow can mint smoke evidence. |
|
firecracker-smoke
command
Command firecracker-smoke runs the protected no-NIC Firecracker smoke path only after its exact runner, fixture, and Jailer inputs are present.
|
Command firecracker-smoke runs the protected no-NIC Firecracker smoke path only after its exact runner, fixture, and Jailer inputs are present. |
|
generate-requirement-manifest
command
Command generate-requirement-manifest renders canonical evidence metadata.
|
Command generate-requirement-manifest renders canonical evidence metadata. |
|
generate-runtime-openapi
command
Command generate-runtime-openapi derives private server and SDK route tables from the public OpenAPI authority.
|
Command generate-runtime-openapi derives private server and SDK route tables from the public OpenAPI authority. |
|
ledger-report
command
Command ledger-report validates a machine-readable weighted evidence ledger.
|
Command ledger-report validates a machine-readable weighted evidence ledger. |
|
milestone-notify
command
Command milestone-notify retains and sends a bounded milestone completion report.
|
Command milestone-notify retains and sends a bounded milestone completion report. |
|
no-real-wait
command
Command no-real-wait verifies owned Go source has no real-time wait primitive.
|
Command no-real-wait verifies owned Go source has no real-time wait primitive. |
|
release-readiness
command
Command release-readiness writes the immutable release hand-off for the current clean main checkout.
|
Command release-readiness writes the immutable release hand-off for the current clean main checkout. |
|
research-dossier-evidence
command
Command research-dossier-evidence records and validates the bounded report produced only after the Research Dossier public E2E has passed.
|
Command research-dossier-evidence records and validates the bounded report produced only after the Research Dossier public E2E has passed. |
|
runtime
command
Command runtime composes one validated Agent Runtime process role.
|
Command runtime composes one validated Agent Runtime process role. |
|
runtime-operations-direct-lab
command
Command runtime-operations-direct-lab records an explicitly authorized, disposable local or home-lab operations exercise.
|
Command runtime-operations-direct-lab records an explicitly authorized, disposable local or home-lab operations exercise. |
|
runtime-operations-drill
command
Command runtime-operations-drill records one protected operational drill.
|
Command runtime-operations-drill records one protected operational drill. |
|
runtime-operations-rehearsal
command
Command runtime-operations-rehearsal exercises the protected drill checks against disposable local services.
|
Command runtime-operations-rehearsal exercises the protected drill checks against disposable local services. |
|
sandbox-control
command
|
|
|
sandbox-host
command
|
|
|
sandbox-host-bootstrap
command
Command sandbox-host-bootstrap reconciles one mounted local/CI host identity into the sandbox-control PostgreSQL ledger.
|
Command sandbox-host-bootstrap reconciles one mounted local/CI host identity into the sandbox-control PostgreSQL ledger. |
|
sandbox-reaper
command
|
|
|
stackctl
command
Command stackctl renders and inspects reviewed declarative Stack documents.
|
Command stackctl renders and inspects reviewed declarative Stack documents. |
|
subscription-model-canary
command
Command subscription-model-canary validates a protected subscription-model canary contract.
|
Command subscription-model-canary validates a protected subscription-model canary contract. |
|
deploy
|
|
|
runtimeoperations/local
command
audit-sink is a disposable TLS endpoint for the local M5 rehearsal.
|
audit-sink is a disposable TLS endpoint for the local M5 rehearsal. |
|
examples
|
|
|
durable-chat
Package durablechat is the public-contract Durable Chat example.
|
Package durablechat is the public-contract Durable Chat example. |
|
durable-chat/cmd/durable-chat
command
Command durable-chat runs the Durable Chat web or terminal example through Agent Runtime's public Go SDK only.
|
Command durable-chat runs the Durable Chat web or terminal example through Agent Runtime's public Go SDK only. |
|
research-dossier
Package researchdossier is the public-contract Research Dossier application.
|
Package researchdossier is the public-contract Research Dossier application. |
|
research-dossier/cmd/research-dossier
command
Command research-dossier runs the Research Dossier web or terminal example through Agent Runtime's public Go SDK only.
|
Command research-dossier runs the Research Dossier web or terminal example through Agent Runtime's public Go SDK only. |
|
workspace-agent
Package workspaceagent is the public-contract Workspace Agent application.
|
Package workspaceagent is the public-contract Workspace Agent application. |
|
workspace-agent/cmd/workspace-agent
command
Command workspace-agent runs the public Workspace Agent approval UI.
|
Command workspace-agent runs the public Workspace Agent approval UI. |
|
internal
|
|
|
afkevidence
Package afkevidence validates bounded, secret-safe direct-main evidence logs.
|
Package afkevidence validates bounded, secret-safe direct-main evidence logs. |
|
agentspecbackfill
Package agentspecbackfill owns the pure immutable request, verification, and archive seam for Agent-spec backfill.
|
Package agentspecbackfill owns the pure immutable request, verification, and archive seam for Agent-spec backfill. |
|
agentspecbackfillcr
Package agentspecbackfillcr owns the structural, canonical AgentSpecBackfill request and status wires.
|
Package agentspecbackfillcr owns the structural, canonical AgentSpecBackfill request and status wires. |
|
agentspecbackfillcrd
Package agentspecbackfillcrd renders and validates the structural AgentSpecBackfill Kubernetes CRD.
|
Package agentspecbackfillcrd renders and validates the structural AgentSpecBackfill Kubernetes CRD. |
|
agentspecbackfillexportprocess
Package agentspecbackfillexportprocess composes the separately-authorized terminal archive exporter.
|
Package agentspecbackfillexportprocess composes the separately-authorized terminal archive exporter. |
|
agentspecbackfillkube
Package agentspecbackfillkube adapts the fixed AgentSpecBackfill Kubernetes resource to controller ports.
|
Package agentspecbackfillkube adapts the fixed AgentSpecBackfill Kubernetes resource to controller ports. |
|
agentspecbackfillprocess
Package agentspecbackfillprocess composes the AgentSpecBackfill controller from explicit, narrow ports.
|
Package agentspecbackfillprocess composes the AgentSpecBackfill controller from explicit, narrow ports. |
|
approval
Package approval owns the pure, persistence-free human-approval state machine.
|
Package approval owns the pure, persistence-free human-approval state machine. |
|
clock
Package clock provides explicit time sources for deterministic runtime decisions.
|
Package clock provides explicit time sources for deterministic runtime decisions. |
|
docsrefresh
Package docsrefresh deterministically renders allow-listed public documentation.
|
Package docsrefresh deterministically renders allow-listed public documentation. |
|
egressproxy
Package egressproxy provides an exact-target forward proxy for trust-scoped workloads.
|
Package egressproxy provides an exact-target forward proxy for trust-scoped workloads. |
|
firecracker
Package firecracker owns the Linux/KVM-only, internal Firecracker host profile.
|
Package firecracker owns the Linux/KVM-only, internal Firecracker host profile. |
|
firecrackerbootprobecomposition
Package firecrackerbootprobecomposition owns the private M4 command handoff.
|
Package firecrackerbootprobecomposition owns the private M4 command handoff. |
|
firecrackerbootprobejournal
Package firecrackerbootprobejournal owns the host-instance-exclusive durable launch-intent record required before an M4 Jailer may start.
|
Package firecrackerbootprobejournal owns the host-instance-exclusive durable launch-intent record required before an M4 Jailer may start. |
|
firecrackerbootprobelease
Package firecrackerbootprobelease owns the private persisted lease guard for one sealed Firecracker boot probe.
|
Package firecrackerbootprobelease owns the private persisted lease guard for one sealed Firecracker boot probe. |
|
firecrackerbootprobeprotocol
Package firecrackerbootprobeprotocol owns the private signed M3-to-M4 boot-probe command and M4 observation wire.
|
Package firecrackerbootprobeprotocol owns the private signed M3-to-M4 boot-probe command and M4 observation wire. |
|
firecrackerbootprobev2
Package firecrackerbootprobev2 owns the private, persisted successor and acknowledgement contract for one sealed Firecracker boot-probe lease.
|
Package firecrackerbootprobev2 owns the private, persisted successor and acknowledgement contract for one sealed Firecracker boot-probe lease. |
|
firecrackerlaunchgrant
Package firecrackerlaunchgrant owns the private, operator-only M3/M4 boot-probe binding.
|
Package firecrackerlaunchgrant owns the private, operator-only M3/M4 boot-probe binding. |
|
identity
Package identity defines runtime-owned opaque identifiers.
|
Package identity defines runtime-owned opaque identifiers. |
|
localdemoworker
Package localdemoworker composes the declared deterministic local Stack fixture.
|
Package localdemoworker composes the declared deterministic local Stack fixture. |
|
mcptool
Package mcptool implements the private, bounded Streamable HTTP MCP client used by the runtime tool adapter.
|
Package mcptool implements the private, bounded Streamable HTTP MCP client used by the runtime tool adapter. |
|
milestone
Package milestone builds retained status evidence and notification attempts.
|
Package milestone builds retained status evidence and notification attempts. |
|
nowait
Package nowait checks owned Go code for nondeterministic real-time waiting.
|
Package nowait checks owned Go code for nondeterministic real-time waiting. |
|
openapicontract
Package openapicontract validates the repository-owned public Agent Runtime OpenAPI contract.
|
Package openapicontract validates the repository-owned public Agent Runtime OpenAPI contract. |
|
providers/codexsubscription
Package codexsubscription owns the fail-closed Codex subscription release gate.
|
Package codexsubscription owns the fail-closed Codex subscription release gate. |
|
roles
Package roles validates trust-scoped runtime process composition.
|
Package roles validates trust-scoped runtime process composition. |
|
runtime/kernel
Package kernel owns deterministic Agent, Session, Input, Turn, and Product-event transitions.
|
Package kernel owns deterministic Agent, Session, Input, Turn, and Product-event transitions. |
|
runtimeadmission
Package runtimeadmission owns the content-reference and durable SendInput admission seam.
|
Package runtimeadmission owns the content-reference and durable SendInput admission seam. |
|
runtimeapi
Package runtimeapi exposes the public, Temporal-free HTTP boundary of Agent Runtime.
|
Package runtimeapi exposes the public, Temporal-free HTTP boundary of Agent Runtime. |
|
runtimeapiprocess
Package runtimeapiprocess composes the separately runnable public API role from explicit operator configuration.
|
Package runtimeapiprocess composes the separately runnable public API role from explicit operator configuration. |
|
runtimeconfig
Package runtimeconfig defines explicit, validated process configuration.
|
Package runtimeconfig defines explicit, validated process configuration. |
|
runtimecontent
Package runtimecontent owns runtime-scoped immutable Agent specification and Input content.
|
Package runtimecontent owns runtime-scoped immutable Agent specification and Input content. |
|
runtimeerror
Package runtimeerror adds safe context at runtime boundaries.
|
Package runtimeerror adds safe context at runtime boundaries. |
|
runtimemodel
Package runtimemodel owns the narrow model-effect worker seam.
|
Package runtimemodel owns the narrow model-effect worker seam. |
|
runtimeoperations
Package runtimeoperations owns the protected operational-evidence drill.
|
Package runtimeoperations owns the protected operational-evidence drill. |
|
runtimeorchestration
Package runtimeorchestration contains the private Temporal composition for state-backed Session work.
|
Package runtimeorchestration contains the private Temporal composition for state-backed Session work. |
|
runtimepostgres
Package runtimepostgres owns the PostgreSQL implementation of runtime-state persistence.
|
Package runtimepostgres owns the PostgreSQL implementation of runtime-state persistence. |
|
runtimestate
Package runtimestate defines the metadata-only S2/S7 runtime lifecycle authority.
|
Package runtimestate defines the metadata-only S2/S7 runtime lifecycle authority. |
|
runtimetool
Package runtimetool owns capability-bound external tool execution.
|
Package runtimetool owns capability-bound external tool execution. |
|
sandboxauthority
Package sandboxauthority implements internal command-secret and egress authority contracts.
|
Package sandboxauthority implements internal command-secret and egress authority contracts. |
|
sandboxcontrolapi
Package sandboxcontrolapi serves the private sandbox.control/v1 control process without exposing persistence, authentication, or transport types in the public sandbox SDK.
|
Package sandboxcontrolapi serves the private sandbox.control/v1 control process without exposing persistence, authentication, or transport types in the public sandbox SDK. |
|
sandboxcontrolprocess
Package sandboxcontrolprocess composes the separately runnable sandbox control role from one strict operator document and explicit secret sources.
|
Package sandboxcontrolprocess composes the separately runnable sandbox control role from one strict operator document and explicit secret sources. |
|
sandboxhostapi
Package sandboxhostapi exposes the private mutually authenticated host control surface.
|
Package sandboxhostapi exposes the private mutually authenticated host control surface. |
|
sandboxhostbootstrap
Package sandboxhostbootstrap enrolls one already-mounted local or CI host identity in the sandbox control ledger.
|
Package sandboxhostbootstrap enrolls one already-mounted local or CI host identity in the sandbox control ledger. |
|
sandboxhostjournal
Package sandboxhostjournal persists the reference host's receipt journal before any fake effect.
|
Package sandboxhostjournal persists the reference host's receipt journal before any fake effect. |
|
sandboxhostprocess
Package sandboxhostprocess composes the separately runnable reference host.
|
Package sandboxhostprocess composes the separately runnable reference host. |
|
sandboxhostprotocol
Package sandboxhostprotocol owns the private, bounded host-control wire contract.
|
Package sandboxhostprotocol owns the private, bounded host-control wire contract. |
|
sandboxreaperprocess
Package sandboxreaperprocess composes the independently deployable durable sandbox reconciliation owner.
|
Package sandboxreaperprocess composes the independently deployable durable sandbox reconciliation owner. |
|
sandboxresource
Package sandboxresource owns durable, principal-scoped volume, snapshot and mount-lease manifests.
|
Package sandboxresource owns durable, principal-scoped volume, snapshot and mount-lease manifests. |
|
sandboxtransfer
Package sandboxtransfer implements the bounded portable workspace transfer data plane used by sandbox host adapters.
|
Package sandboxtransfer implements the bounded portable workspace transfer data plane used by sandbox host adapters. |
|
stack
Package stack defines the typed desired-state input for operator-owned infrastructure.
|
Package stack defines the typed desired-state input for operator-owned infrastructure. |
|
subscriptioncanary
Package subscriptioncanary validates the operator contract required before a protected subscription-model canary.
|
Package subscriptioncanary validates the operator contract required before a protected subscription-model canary. |
|
temporalpayloadruntime
Package temporalpayloadruntime owns the sole runtime Temporal client and worker converter factory.
|
Package temporalpayloadruntime owns the sole runtime Temporal client and worker converter factory. |
|
temporalpayloaduiprocess
Package temporalpayloaduiprocess composes the local Temporal UI payload-inspection handler from explicit policy.
|
Package temporalpayloaduiprocess composes the local Temporal UI payload-inspection handler from explicit policy. |
|
tooldispatch
Package tooldispatch exposes the private trigger boundary for broker-owned tool dispatch.
|
Package tooldispatch exposes the private trigger boundary for broker-owned tool dispatch. |
|
toolpolicy
Package toolpolicy evaluates one already-normalized tool intent against one immutable operator-authored policy projection.
|
Package toolpolicy evaluates one already-normalized tool intent against one immutable operator-authored policy projection. |
|
toolschema
Package toolschema owns the deliberately small, versioned JSON Schema profile used by model-visible tool catalogs.
|
Package toolschema owns the deliberately small, versioned JSON Schema profile used by model-visible tool catalogs. |
|
Package sandbox defines the public durable sandbox control contract.
|
Package sandbox defines the public durable sandbox control contract. |
|
sdk
|
|
|
go
Package agentruntime defines the stable, Temporal-free Go contract for Agent Runtime.
|
Package agentruntime defines the stable, Temporal-free Go contract for Agent Runtime. |
|
skills
|
|
|
refresh-agent-runtime-docs/scripts/refresh-docs
command
Command refresh-docs regenerates allow-listed public documentation from declared sources.
|
Command refresh-docs regenerates allow-listed public documentation from declared sources. |
|
Package temporalpayload provides the local, size-aware Temporal payload codec chain.
|
Package temporalpayload provides the local, size-aware Temporal payload codec chain. |
|
s3
Package s3 adapts an S3-compatible object store to temporalpayload.BlobStore.
|
Package s3 adapts an S3-compatible object store to temporalpayload.BlobStore. |
|
tools
|
|
|
dev
command
Command dev owns the explicit local-only Stack materialization lifecycle.
|
Command dev owns the explicit local-only Stack materialization lifecycle. |
|
firecracker/guest-agent
command
Command guest-agent is the project-owned, static smoke-fixture init program.
|
Command guest-agent is the project-owned, static smoke-fixture init program. |
Click to show internal directories.
Click to hide internal directories.