Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
e5f344a
oidcjwt: take signing keys from a KeySource, and expose Substrate cla…
ILLUM1N0X Oct 15, 2026
0c2776a
hack: ATE_KIND_RESERVED_CPU reserves kubelet and system CPU on kind n…
dims Oct 15, 2026
35c6ab2
ate-api-server applies atelet's ReportActorSnapshotState reports (#2622)
igooch Oct 15, 2026
f4f7b80
hack/verify: run the benchmarking Python suites (#2709)
ygao-g Oct 15, 2026
7a51ad1
Remove the pause operation label (#2701)
zoez7 Oct 15, 2026
c673b8a
Update unknown request rules in api-style-guide (#2711)
HavenXia Oct 15, 2026
8e157bb
ate-setup: use the envoy-dataplane image in atenet-router (#2655)
panchoruy Oct 15, 2026
b83d607
Router authn/z part 2.5: podcertcontroller: Don't load pod in podiden…
ahmedtd Oct 15, 2026
a68c7e1
ate-api-server can apply the snapshot state Checkpoint returns, and l…
igooch Oct 15, 2026
316ac86
atunnel refactor (#2720)
bowei Oct 15, 2026
46f89c8
atelet API: add DetachActor, which uploads an actor's latest local sn…
igooch Oct 15, 2026
eb7b034
objectstore-plugin: derive actor storage grants and mint downscoped G…
ILLUM1N0X Oct 15, 2026
ac296df
ate-api-server: Create one unified configuration file (#2021)
ahmedtd Oct 15, 2026
088381b
atenet: Router checks the routed worker's SPIFFE ID on atunnel's cert…
LiorLieberman Oct 15, 2026
84acd9a
atenet-egress: log every failed request, sample successes at 1% (#2693)
ygao-g Oct 15, 2026
d905e95
docs: introduce zero-trust security as a co-equal pillar in README (#…
destijl Oct 15, 2026
ef193d1
Mint worker-for-actor certificates only for the Worker that the actor…
aramase Oct 15, 2026
9bb68ca
benchmarking: plumb the actor CPU limit through deploy.sh and the orc…
maxsmythe Oct 15, 2026
def6e2b
benchmarking/sweperf: run each trajectory on a fresh actor (#2323)
pmandewalkar Oct 15, 2026
024190e
Limit memory used by concurrent snapshot uploads (#2708)
EItanya Oct 16, 2026
a153e10
fix(ateom-gvisor): isolate and evict checkpoint page cache to prevent…
chw120 Oct 16, 2026
03ab78e
benchmarking: generate sweperf ActorTemplates from an image catalog (…
pmandewalkar Oct 16, 2026
a1471f0
Suspend and pause preserve concurrent actor crashes and report failur…
cloudonly Oct 16, 2026
321332e
imagecache: read mountinfo lines of any length; fix two tests for 64 …
dims Oct 16, 2026
97de17b
atelet: make durable-dir volumes writable by non-root containers (#1906)
dims Oct 16, 2026
5d7a890
benchmarking: record Kubernetes version, worker capacity and run meta…
Nishanth29 Oct 16, 2026
2b3a406
Merge the pause workflow into the suspend workflow (#2694)
zoez7 Oct 16, 2026
68a082c
Use a Go vanity import in the "main" substrate repo: go.ate.dev/subst…
thockin Oct 16, 2026
603e006
skip device nodes when unpacking image layers (#2739)
BenTheElder Oct 16, 2026
3619701
atelet, ateworker: probe CPU features and watch sandbox-runtimes.json…
shrutiyam-glitch Oct 16, 2026
c4518a1
ate-setup: enforce ateapi authorization by default and manage access …
SHRUTI6991 Oct 16, 2026
4595c2b
Merge upstream API authorization and worker runtime updates
EItanya Oct 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .github/workflows/release.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ jobs:
for arch in amd64 arm64; do
CGO_ENABLED=0 GOOS="${os}" GOARCH="${arch}" go build \
-trimpath \
-ldflags="-s -w -X=github.com/agent-substrate/substrate/internal/version.Version=${VERSION}" \
-ldflags="-s -w -X=go.ate.dev/substrate/internal/version.Version=${VERSION}" \
-o "dist/kubectl-ate-${os}-${arch}" \
./cmd/kubectl-ate
done
Expand Down
2 changes: 1 addition & 1 deletion .golangci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ linters:
- "!**/cmd/ateworker-*/**"
- "!**/internal/ateworker/**"
deny:
- pkg: github.com/agent-substrate/substrate/internal/ateworker
- pkg: go.ate.dev/substrate/internal/ateworker
desc: only the ateworker binaries may import internal/ateworker

errcheck:
Expand Down
4 changes: 2 additions & 2 deletions .ko.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ defaultPlatforms:
- linux/arm64

baseImageOverrides:
github.com/agent-substrate/substrate/demos/sandbox: alpine:3.24.2@sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6
go.ate.dev/substrate/demos/sandbox: alpine:3.24.2@sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6
# atelet needs glibc to run the node's kubelet credential provider, which
# some platforms ship dynamically linked (e.g. AKS, GKE Ubuntu).
github.com/agent-substrate/substrate/cmd/atelet: gcr.io/distroless/base-debian13:latest@sha256:389cad21f73e4c37b94ffe5b13736d5a92bd5bd3c6c6b38c2be1c881e14ba2bd
go.ate.dev/substrate/cmd/atelet: gcr.io/distroless/base-debian13:latest@sha256:389cad21f73e4c37b94ffe5b13736d5a92bd5bd3c6c6b38c2be1c881e14ba2bd
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,5 +104,6 @@ Keep this up to date when updating AGENTS.md.
- **Workload Isolation**: The project uses `gVisor` (`runsc`) for sandboxing and security isolation of workloads on pods.
- **JWTs and JWKs**: Signing (`internal/localjwtauthority`), verification (`internal/oidcjwt`), and JWK set publishing (`internal/oidcdiscovery`) are built on the standard library's crypto packages. Extend those packages rather than adding go-jose or another JOSE library, so the code that decides whether a token is valid stays small and supports only the algorithms Substrate uses.
- **Ingress Authentication**: `atenet-router --ingress-auth-mode=static-mtls` requires clients to present a SPIFFE certificate signed by `--ingress-client-ca-file` whose ID is in `--ingress-allowed-spiffe-ids`; that list is the whole authorization policy, so any listed client may reach any Actor. The default, `deprecated-insecure`, checks a certificate only when a client presents one, and also serves plaintext listeners that accept any client. Install with it via `ate-setup --ingress-auth-mode=static-mtls` (`manifests/ate-install/components/router-static-mtls`); the allowlist lives in `manifests/ate-install/atenet-router.yaml`.
- **Control API Authorization**: `ate-api-server` checks every Control RPC against an embedded OpenFGA model (`cmd/ateapi/internal/authz/model.fga`), on by default. Every served unary RPC needs an entry in `defaultRPCPermissions` (`registry.go`): with enforcement on, an RPC without one is denied, and a test fails the build. Access is granted per global scope and atespace through AccessPolicy (`kubectl ate access-policy`); the install's bootstrap owner is the shared `ate-client` ServiceAccount that `kubectl ate` uses. See `docs/authorization.md` for roles and known gaps.

For future plans for security, reference `docs/roadmap.md`.
54 changes: 30 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,57 +7,63 @@

# Agent Substrate

**A secure-by-default runtime for running millions of agent sandboxes on Kubernetes.**
**Zero-trust sandboxing for millions of agents on Kubernetes.**

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[Quickstart](#quickstart-development) · [Architecture](docs/architecture.md) · [Roadmap](docs/roadmap.md) · [Contributing](CONTRIBUTING.md)
[Quickstart](#quickstart-development) · [Security](docs/security.md) · [Architecture](docs/architecture.md) · [Roadmap](docs/roadmap.md) · [Contributing](CONTRIBUTING.md)

</div>

## What is Agent Substrate?

Agent Substrate is a secure-by-default agent execution runtime engineered to run millions of sandboxes with 10x higher density than standard container runtimes. Purpose-built for the era of autonomous agents, Substrate delivers sub-500ms resume operations at over 500 suspend/resume activations per second with native zero-trust kernel and network isolation. It supports multiple sandbox technologies including microVMs and gVisor, enabling consistent lifecycle operations for all sandbox types.
Agent Substrate is a security-hardened, zero-trust runtime for sandboxed agents, engineered to safely run millions of agents and tools with 10x higher density than standard containers. Purpose-built for the era of autonomous agents, Substrate delivers fast resume operations in less than 400ms, with more than 1500 activations per second. Agents get isolated compute, identity, networking, and storage. Sensitive credentials are kept out of reach from untrusted code. It supports multiple sandbox technologies, including microVMs and gVisor, while enabling a consistent lifecycle and management of all sandboxes.

At its core, Agent Substrate maps a larger set of “actors” (applications such as agents) onto a smaller set of ready “workers”, relying on the fact that agent-like applications tend to be idle most of the time to achieve heavy multiplexing. It provides functionality to manage an actor’s lifecycle (e.g. create/destroy, suspend/resume), to assign actors to workers in real time, and to route incoming traffic to them.
At its core, Agent Substrate maps a larger set of “actors” (stateful workloads such as agents) onto a smaller pool of ready “workers”. Because agents spend most of their lives waiting on models, tools, or humans, Substrate snapshots idle actors out of memory and restores them when a request arrives.

Agent Substrate is intended to be a low-opinion system. The workloads it manages don't have to be literal AI agents, but those are the best example of the kind of applications it is designed for. It is not an SDK for building agents, but rather a system for running them at scale.
Substrate is a low-opinion runtime, not an agent SDK. The workloads it runs do not have to be AI agents, though autonomous, untrusted, mostly-idle agents are the target for its isolation and scheduling model. It runs on standard Kubernetes: Pods, autoscaling, NetworkPolicies. It adds agent-specific scheduling, snapshotting, identity, and network mediation. This allows agentic, inference, training, and reinforcement learning workloads to share one infrastructure plane.

Agent Substrate leverages Kubernetes for the infrastructure provisioning and worker lifecycle management (Kubernetes Pods). It builds on top of Kubernetes features like Pods and Pod autoscaling, while Agent Substrate provides agent-specific scheduling and control to achieve lower latency. Using Kubernetes as the underlying system enables consistent infrastructure management across all workloads types that are required for end to end agentic deployments and allows holistic infrastructure optimizations for RL scenarios that span agentic, inference and training cycles.
## Security Model

## Star History
Substrate treats every actor as untrusted and mutually hostile, so tenants can share physical nodes without sharing a security boundary. Every control operates within the cold-start and resume budget. See the [Security Guide](docs/security.md) for the full list of security principles and threat model.

<a href="https://www.star-history.com/?repos=agent-substrate%2Fsubstrate&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=agent-substrate/substrate&type=date&theme=dark&legend=top-left">
<img alt="Star history chart for agent-substrate/substrate" src="https://api.star-history.com/svg?repos=agent-substrate/substrate&type=date&legend=top-left">
</picture>
</a>
* **Always sandboxed, VM-grade boundaries:** Every actor runs inside a dedicated [gVisor](https://gvisor.dev/) (`runsc`) or [Cloud Hypervisor](https://www.cloudhypervisor.org/) microVM sandbox with segregated compute, network, and storage. Plain Linux containers are not supported.
* **Per-agent cryptographic identity:** Every active actor receives a short-lived [SPIFFE](https://spiffe.io/) X.509 certificate by default, and the egress gateway can mint per-actor JWTs on demand when an egress policy calls for one. Both carry the actor identity and atespace (the Substrate namespace grouping), and are designed to federate with external identity systems.
* **Zero credentials in the sandbox:** Actors never hold actor identity JWTs/certs, API keys, or cloud tokens. The built-in egress gateway ([`atenet-egress`](docs/egress-credential-injection.md)) injects credentials into approved outbound requests outside the sandbox, so a prompt-injected or compromised agent has nothing to exfiltrate.
* **Default-deny networking:** Actors start with a private network stack, no inbound path except through the ingress router (`atenet-router`), no lateral actor-to-actor or control-plane access, and outbound traffic [restricted by the egress gateway](docs/egress-traffic.md).
* **Pluggable policy at the edge:** The egress gateway acts as an external Policy Enforcement Point (PEP) that is fully replaceable, allowing you to attach your own authorization, DLP, prompt-injection scanning, or cloud IAM policy engine without placing policy code inside the untrusted sandbox.

## Demo
## Performance & Multiplexing

[![Agent Substrate Demo](https://img.youtube.com/vi/ZEzkCFJkzjY/hq1.jpg)](https://www.youtube.com/watch?v=ZEzkCFJkzjY)

*Watch the Agent Substrate cluster multiplex ~250 stateful actors across just 8 physical pods.*

This demo highlights the core developer experience and "Agentic Infrastructure" capabilities of Substrate:

1. **Actor Teleport:** High-performance suspend and resume of actors onto any available worker in the pool with sub-second activation.
2. **State Persistence:** Persistent working memory (volatile RAM) and filesystem state preserved perfectly across hibernation cycles via full-state snapshots.
3. **Agent Multiplexing:** Demonstrates 30x+ oversubscription by "juggling" a large registry of stateful actors onto a small pool of shared physical pods.
1. **Actor Teleport:** Suspend and resume actors onto any available worker in the pool, when needed.
2. **Full-State Persistence:** Working memory (RAM) and filesystem state are captured in snapshots and restored intact across hibernation cycles, without losing in-flight sessions or tool state.
3. **10x–30x Oversubscription:** Multiplex a large registry of stateful actors onto a small pool of warm worker pods, paying for compute only while an agent is actively thinking or executing a tool.

To reproduce this demo in your own cluster, please refer to the detailed walkthrough in the **[Counter Demo](demos/counter/README.md)**.
To reproduce this demo in your own cluster, see the **[Counter Demo](demos/counter/README.md)**. For more walkthroughs, visit the **[agent-substrate YouTube channel](https://www.youtube.com/channel/UCN9PPqlTtVxlcpbQ-NWpfZQ)**.

For more videos and walkthroughs, visit our YouTube channel: **[agent-substrate](https://www.youtube.com/channel/UCN9PPqlTtVxlcpbQ-NWpfZQ)**.
## Star History

<a href="https://www.star-history.com/?repos=agent-substrate%2Fsubstrate&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=agent-substrate/substrate&type=date&theme=dark&legend=top-left">
<img alt="Star history chart for agent-substrate/substrate" src="https://api.star-history.com/svg?repos=agent-substrate/substrate&type=date&legend=top-left">
</picture>
</a>

## Framework Agnostic & Compatibility

Agent Substrate is designed to be **framework and agent harness agnostic**. Because it manages standard OCI containers at the kernel level (via gVisor), it can host agents built on any stack.
Agent Substrate is **framework and agent harness agnostic**. Because it runs standard OCI container images inside gVisor or microVM sandboxes and enforces security outside the workload, it hosts agents built on any stack without SDK changes:

* **Agent Development Kit (ADK):** Support for ADK agents with session state preservation across invocations as actor state. Ideal for all types of agents and stateful tool or subagent calls.
* **LangChain:** Ideal execution environment for LangChain agents and tool calls.
* **Claude Code, CodeX, and Antigravity:** Support for high-density, stateful coding environments that preserve system state and filesystem state across sessions.
* **Model Context Protocol (MCP):** Support for deploying secure, sandboxed MCP servers as Substrate Actors to provide durable tools for any model.
* **Agent Development Kit (ADK):** Preserves session state across invocations as actor state.
* **LangChain:** Drop-in execution environment for LangChain agents and tool calls.
* **Claude Code, Codex, and Antigravity:** High-density, stateful coding environments that keep system and filesystem state across sessions while isolating untrusted code execution.
* **Model Context Protocol (MCP):** Deploy sandboxed MCP servers as Substrate Actors with per-actor identity and egress controls.

## Ecosystem & Examples

Expand Down
Loading
Loading