README

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 highly efficient, declarative orchestrator to run millions of autonomous agent workloads in a cluster. It runs on top of Agent Substrate for sandboxed execution and is built to run millions of tasks per cluster. If you have used Kubernetes, ax will feel similar.

yaml
 task.yaml
apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: golang
spec:
  git:
    - repo: https://github.com/golang/go.git
      branch: "my-fix"
  files:
    - path: "AGENTS.md"
      content: |
        - Run go test to ensure that tests are passing.
        - Do not modify the public API.
---
apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: test
spec:
  image: "ghcr.io/my-org/my-coding-agent@sha256:..."
  config:
    goal: "Fix what's broken please."
  workspace:
    name: golang
  debug: true    enables ax ssh


Then apply it, check on it, and look over the agent's shoulder:

bash
ax apply -f task.yaml
ax describe task test
ax ssh test -- ls -al /workspace


 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
- Podman or Docker, authenticated to 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:

bash
kubectl get svc api -n ate-system


 1. Install the CLI

bash
go install github.com/google/ax/cmd/ax@latest


This puts the ax binary in $(go env GOPATH)/bin. Ma