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.

# task.yaml
apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: golang
spec:
  git:
repo: https://github.com/golang/go.git
      branch: "my-fix"
---
apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: test
spec:
  workspaces:
name: golang
      goal: "Ensure that Go tool chain is available and is built from source"
  debug: true   # lets you ax ssh into the sandbox

Then apply it, watch it come up, and look over the agent's shoulder:

ax apply -f task.yaml
ax watch 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
• 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:

kubectl get svc api -n ate-system

1. Install the CLI

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

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:

make deploy AX_IMAGE_REPO=

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

ax apply -f examples/task.yaml       # Task + Workspace + Model in one file
ax get tasks
NAME      ATESPACE   PHASE     ACTOR           WORKER-IP    AGE
task123   default    Running   task123         10.20.3.67   1m
ax watch task task123                # stream phase and condition changes live
ax ssh task123 -- ls -la /workspace  # poke around inside the sandbox
ax suspend task task123              # checkpoint and pause
ax resume task task123               # pick up where it left off

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 each do, and how a task moves through phases and conditions. | | Manifests | Write your own YAML, with an annotated example of every kind. | | Sandbox | See what the runner does on boot and what your command can rely on: metadata server, guest services, environment. | | Runners | Understand the contract between the control plane and the task container, and build your own runner image to replace the default. | | Networking | Reach a running task through the atenet router from the cluster, your laptop, or a gRPC client. | | Architecture | Understand how the control plane fits together, plus the API reference. | | Development | Build, test, and ship changes to AX itself. | | Roadmap | See planned milestones across core specs, actor architecture, agentic environments, and governance. |

CLI usage

ax talks to the control plane over gRPC. It is deliberately kubectl-shaped: apply, get, describe, watch, delete, plus a few agent-specific verbs.

Everyday commands

# Apply anything (multi-document YAML, file or stdin)
ax apply -f examples/task.yaml
Tasks
ax get tasks                          # list
ax get tasks -a my-atespace           # list in another atespace
ax get task task123                   # full spec + live status as YAML
ax describe task task123              # human-readable detail
ax watch task task123                 # stream status and condition transitions
ax suspend task task123               # checkpoint actor state and pause
ax resume task task123                # resume a suspended task
ax delete task task123
Shell into the running sandbox
ax ssh task123                        # interactive shell (task needs spec.debug: true)
ax ssh task123 -- ls -la /workspace   # one-off command
ax ssh task123 -- python3 main.py
Workspaces and models follow the same pattern
ax get workspaces
NAME                ATESPACE   GIT-REPOS   MCP-SERVERS
default-workspace   default    1           1
ax describe workspace default-workspace
ax delete workspace default-workspace

ax get models
NAME            ATESPACE   PROVIDER   MODEL
default-model   default    google     gemini-3.8-flash
ax describe model default-model
ax delete model default-model

Connection plumbing
ax ctx                                # active kube context and how ax is reaching the control plane
ax tunnel list                        # background tunnels (state lives in ~/.ax/tunnels)
ax tunnel stop
ax version

Works with kubectx

ax follows your active Kubernetes context. Switch clusters and ax resolves and tunnels to that cluster's control plane in the background.

kubectx staging-cluster
ax get tasks
kubectx prod-cluster
ax get tasks
Or target a context without switching
ax --context=dev-cluster get tasks

Global flags

| Flag | Description | Default | |---|---|---| | -a, --atespace | Atespace scope for the command | default | | -n, --namespace | Kubernetes namespace where AX is installed | ax-system | | --context | Kubernetes context to target | active kubectx / current-context | | --server | Control plane address, bypassing auto-detection | derived from kube context, or $AX_SERVER |

License

Apache License 2.0. See LICENSE for details.