google / ax

AX
> [!WARNING]
> AX and several of its features are in heavy development. We are actively
> refining our core concepts, protocols, and specifications, and will likely
> introduce major breaking changes prior to a stable release.
**Declare an agentic task with workspaces and model specifications. AX sandboxes it, wires up its workspace, and helps running it at scale.**
AX is a high-throughput, declarative orchestrator to run billions of autonomous agent workloads in a cluster. It runs on top of Agent Substrate for sandboxed execution and is built to run billions of tasks per cluster. If you have used Kubernetes, `ax` will feel similar.
 [code] 
Then apply it, watch it come up, and look over the agent's shoulder:
 [code] 
## Why?
Agents are a new kind of workload. They are neither stateless microservices nor run-to-completion batch jobs. They accumulate state, need strict isolation, call out to model APIs and tool servers, and can burn money in a loop if nobody is watching. AX gives you three small primitives that handle all of that declaratively:
| You want to... | AX gives you |
|---|---|
| Run untrusted agent code in an isolated sandbox with CPU/memory limits | **`Task`** |
| Pre-wire Git repos, MCP servers, and skill packages so every agent starts warm | **`Workspace`** |
| Configure which LLM the platform itself uses, with credentials from a Kubernetes secret | **`Model`** |
| Pause an idle agent and pick up exactly where it left off | `ax suspend` / `ax resume` |
| Shell into a running agent to see what it is doing | `ax ssh` |
Everything is expressed as `ax.io/v1alpha1` manifests and applied with a single command.
## Quick start
### Prerequisites
AX schedules every task as a sandboxed actor on Agent Substrate, so Substrate must be running in your cluster before you deploy AX. You need:
- A Kubernetes cluster with **Agent Substrate** installed (see below)
- Go and `kubectl`
- `ko` (`brew install ko`) and a container registry your cluster can pull from
To install Agent Substrate, follow the instructions in the Substrate README. Substrate lands in the `ate-system` namespace and exposes its Control API at `api.ate-system.svc.cluster.local:443`, which is where AX expects to find it. Verify it is up before moving on:
 [code] 
### 1. Install the CLI
 [code] 
This puts the `ax` binary in `$(go env GOPATH)/bin`. Make sure that directory is on your `PATH`.
### 2. Deploy the control plane
With the prerequisites in place — most importantly a reachable Agent Substrate Control API — deploy the AX control plane:
 [code] 
This deploys Redis, then builds and deploys the control plane images with `ko`. Everything lands in the `ax-system` namespace.
### 3. Run your first task
 [code] 
Want to see the whole lifecycle end to end? Run `./demo.sh`. It applies a custom workspace, waits for readiness, runs commands over `ax ssh`, and suspends the task.
## Documentation
| Guide | Read it to... |
|---|---|
| Concepts | Learn what a `Task`, `Workspace`, and `Model` ea