Agent Substrate is an open-source system designed to efficiently manage and orchestrate agent-like workloads on top of Kubernetes clusters. Written in Go, it aims to address the scalability and latency limitations of native Kubernetes when running large numbers of stateful, often idle, agent processes. Rather than replacing Kubernetes, Agent Substrate complements it by providing specialized scheduling, lifecycle management, and traffic routing for agents, while Kubernetes continues to handle infrastructure provisioning and general workload management.
The core innovation of Agent Substrate lies in its ability to map a large number of logical "actors" (such as AI agents or similar applications) onto a smaller pool of physical "workers" (Kubernetes Pods). This is based on the observation that many agent-like applications spend most of their time idle, allowing for heavy multiplexing and oversubscription. The system manages the full lifecycle of these actors, including creation, destruction, suspension, resumption, and real-time assignment to available workers. It also ensures that incoming traffic is correctly routed to the appropriate actor, regardless of which worker pod is currently hosting it.
A key feature is the system's low-latency operation, achieved by removing the Kubernetes control plane from the critical path for agent scheduling and activation. This enables sub-second activation of suspended actors, making it suitable for interactive or stateful workloads that require rapid responsiveness. State persistence is another major capability: Agent Substrate can snapshot and restore both volatile memory and filesystem state, ensuring that actors can be suspended and resumed seamlessly without loss of context.
Agent Substrate is designed to be framework-agnostic and compatible with a wide range of agent harnesses and application stacks. It manages standard OCI containers at the kernel level using gVisor, allowing it to host agents built with different technologies, including those using the Agent Development Kit (ADK), LangChain, Claude Code, CodeX, and Model Context Protocol (MCP). This flexibility makes it suitable for running long-lived, stateful AI agents, coding environments, and secure sandboxed tools.
The repository provides several demonstration applications that showcase its capabilities. These include a stateful HTTP counter server, a sandboxed shell environment with persistent filesystem state, a multiplexed Claude Code agent demo, and a "Secret Agent" demo highlighting zero-idle suspension and reanimation. These demos illustrate how Agent Substrate can juggle hundreds of actor sessions across a handful of physical pods, achieving significant resource efficiency.
The system is currently in early development and not recommended for production use. APIs and features are subject to change, and the maintainers caution that backward compatibility is not yet guaranteed. The project supports the latest stable and previous minor releases of Kubernetes. It offers a variety of tools and components, including a gRPC API server for control plane operations, a node-level daemon for managing worker pods and state transfers, a Kubernetes controller for custom resources, networking and proxy controllers, and a CLI tool for resource management.
Agent Substrate is community-driven, with open channels for discussion and contributions. The project welcomes involvement but prioritizes core system development and demonstration applications at this stage. Comprehensive documentation, guides, and sample applications are provided to help users get started and explore the system’s advanced agent orchestration capabilities.
