Learn Agent Substrate | Learn Agent Substrate<br>Skip to content Learn Agent Substrate<br>How agent-substrate works - visualized end to end.

Start with the topology Resume-actor walkthrough View on GitHub

What is Substrate?

Agent Substrate is a Kubernetes-native runtime for highly-multiplexed actor<br>workloads - AI agents, sandboxed environments, stateful services. It decouples<br>actor lifecycle from Pods, so a small pool of pre-warmed gVisor workers can host<br>30× more actors than there are pods , by suspending idle actors to object<br>storage and restoring them on demand.

The bird’s-eye view:

Substrate topology - whiteboard view<br>Client connects to atenet, which consults ateapi (control plane) to find the right worker pod. atelet uploads and downloads snapshots between the worker pod and GCS/S3.

CONTROL PLANE

DATA PLANE · per worker node

SNAPSHOT STORAGE

Client<br>HTTP request<br>actorId.actors…ate.dev

atenet<br>L7 proxy + DNS<br>ExtProc · xDS

ateapi<br>gRPC + workflows<br>source of truth

Redis<br>actors<br>workers<br>locks

atecontroller<br>CRD reconciler<br>WorkerPool · ActorTemplate

atelet<br>DaemonSet<br>drives ateom · ships snapshots

Worker pod · gVisor<br>one actor per pod · pool of N pods

ateom-gvisor<br>Unix socket gRPC

runsc<br>gVisor

workload<br>your code

GCS / S3<br>checkpoint snapshots<br>zstd-compressed

HTTP

ResumeActor<br>(per request)

HTTP after :authority rewrite

Run · Checkpoint · Restore

upload /<br>download<br>(zstd)

The whole system on one whiteboard. Click any box to drill in. For the wiring-diagram<br>version with every port, see System topology.

Where to go next

System topology<br>The static architecture: every binary, every port, every connection.<br>Open →

Resume actor<br>The most interesting flow - touches every component. Cold start from<br>snapshot, end to end.<br>Open →

ateapi internals<br>Control plane API: RPCs, workflow engine, Redis keyspace.<br>Open →

Concepts glossary<br>Quick definitions for the domain terms - actor, worker, session,<br>snapshot, WorkerPool, ActorTemplate.<br>Open Actor →

Source on GitHub<br>Browse the full source, open issues, or read the architecture docs and API guide.<br>agent-substrate/substrate →

How to read this atlas

Mermaid diagrams are the lingua franca: sequence diagrams for flows, state<br>diagrams for lifecycles, flowcharts for topology.

Boxes are clickable in the hero topology above and in every Mermaid<br>diagram on the deeper pages - try clicking ateapi above to drill into its<br>internals.

Code references look like cmd/ateapi/main.go:97 -<br>open those in your editor to confirm any claim made here.

Authoritative sources<br>The atlas is a visual layer over the prose in<br>docs/architecture.md<br>and docs/api-guide.md.<br>When the two disagree, the code wins.