Skip to content
Learn Agent Substrate

Learn Agent Substrate

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 workloads - AI agents, sandboxed environments, stateful services. It decouples actor lifecycle from Pods, so a small pool of pre-warmed sandbox workers - gVisor or micro-VM - can host 30× more actors than there are pods, by suspending idle actors to object storage and restoring them on demand.

Each actor lives in an atespace (Substrate’s tenancy boundary), so its identity is the tuple (atespace, name) - which is why you’ll see that pair in DNS names, storage keys, and every API call throughout this atlas.

The bird’s-eye view:

Substrate topology - whiteboard view 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 HTTP request name.atespace.actors…ate.dev atenet L7 proxy + DNS ExtProc · xDS ateapi gRPC + workflows source of truth Redis actors workers locks atecontroller CRD reconciler WorkerPool · ActorTemplate atelet DaemonSet drives ateom · ships snapshots Worker pod · gVisor one actor per pod · pool of N pods ateom-gvisor Unix socket gRPC runsc gVisor workload your code GCS / S3 checkpoint snapshots zstd-compressed HTTP ResumeActor (per request) HTTP after :authority rewrite Run · Checkpoint · Restore upload / download (zstd)

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

Where to go next

System topology

The static architecture: every binary, every port, every connection. Open →

Resume actor

The most interesting flow - touches every component. Cold start from snapshot, end to end. Open →

ateapi internals

Control plane API: RPCs, workflow engine, Redis keyspace. Open →

Concepts glossary

Quick definitions for the domain terms - actor, atespace, worker, session, snapshot, WorkerPool, ActorTemplate. Open Actor →

How to read this atlas

  • Mermaid diagrams are the lingua franca: sequence diagrams for flows, state diagrams for lifecycles, flowcharts for topology.
  • Boxes are clickable in the hero topology above and in every Mermaid diagram on the deeper pages - try clicking ateapi above to drill into its internals.
  • Code references look like cmd/ateapi/main.go:97 - open those in your editor to confirm any claim made here.