google/ax

▲ 31 stars today★ 14,731⑂ 794

Agent Executor (AX) is Google's open agentic orchestration runtime

About google/ax

google/ax is an open-source project on GitHub, mainly written in Go. Agent Executor (AX) is Google's open agentic orchestration runtime It currently holds 14,731 stars and 794 forks with 98 open issues, and was last pushed on 2026-11-16 (repository created 2026-03-30).

Project Overview

Git Homed tracks it on the Today's Trending board, currently at rank #78 with 31 new stars today.

GitHub Repository Details

Repository google/ax · default branch main · size 45608 KB · watchers 59 · source: GitHub REST API and repository README

README

https://github.com/google/ax/blob/HEAD/AX axolotl 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.

# task.yaml
apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: golang
spec:
  setup:
    git:
  • repo: https://github.com/golang/go.git
ref: "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: profile: image: "ghcr.io/my-org/my-coding-agent@sha256:..." goal: text: "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:

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:

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. Build and push the images

Point AX_IMAGE_REPO at your registry, then build the ax-server and ax-task-runner images and push them to it:

export AX_IMAGE_REPO=   # e.g. gcr.io/my-project
make images

3. Deploy the control plane

With the prerequisites in place — most importantly a reachable Agent Substrate Control API — deploy the AX control plane:

make deploy

This deploys PostgreSQL and the ax-server image you just pushed, configured to use your ax-task-runner image for tasks that do not set spec.profile.image. Everything lands in the ax-system namespace.

4. Create a WorkerPool

Every task runs as a Substrate actor, and an actor needs a free worker from a WorkerPool. Nothing creates one for you — not make deploy, and not the Substrate installer — so without a pool, the first ax resume fails with ResourceExhausted: no free workers available (the task itself stays Suspended).

Create a small gVisor pool from examples/workerpool.yaml (its header explains how to apply it), or follow the WorkerPool step in the installation guide. Then wait until kubectl get workerpools -A shows the workers ready.

5. Run your first task

From your ax checkout:

ax apply -f examples/simple.yaml         # the smallest useful Task
ax resume task simple-task               # new tasks start Suspended; resume schedules the actor and starts it
ax get tasks

NAME ATESPACE STATE ACTOR AGE

simple-task default Working simple-task 1m

ax ssh simple-task -- ls -la /workspace # poke around inside the sandbox ax suspend task simple-task # checkpoint and pause ax resume task simple-task # pick up where it left off

The first resume also waits for the workspace to initialize (cloning its git repos), so it can take a while; if the CLI gives up first, the task keeps coming up in the background — ax get tasks tells you where it is.

Want to see the whole lifecycle end to end? Run ./demo.sh. It applies a custom workspace, resumes the task, runs commands over ax ssh, and suspends it again.

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. | | Observability | Collect ax-server's logs, metrics, traces, and events, and configure where they go. | | 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, delete, plus a few agent-specific verbs.

Everyday commands

# Apply anything (multi-document YAML, file or stdin)
ax apply -f examples/simple.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 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, gateways, 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 gateways

NAME ATESPACE EGRESS-RULES

review-bot-gw default 3

ax describe gateway review-bot-gw ax delete gateway review-bot-gw

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 | | --trace | Trace the command and print its trace ID to stderr. Its RPCs send a sampled W3C traceparent, and CLI spans are exported over OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is set. Without it, the CLI sends no trace context and ax-server samples on its own. See CLI traces | off |

License

Apache License 2.0. See LICENSE for details.

GitHub Stars & Activity

14,731Stars
794Forks
98Open issues
GoLanguage

GitHub Popularity

GitHub stars14,731
Forks794
Open issues98
Primary languageGo
LicenseApache-2.0
Stars gained today31
Created2026-03-30
Last pushed2026-11-16

Trending History

Daily boardrank #78 · ▲ 31 stars

Related GitHub Projects

1

alibaba / open-code-review

Go★ 52,588⑂ 4,224▲ 691 stars
→
2

XTLS / Xray-core

Go★ 42,938⑂ 6,152▲ 27 stars
→
3

getlago / lago

Go★ 10,886⑂ 797▲ 25 stars
→
4

tailscale / tailcat

Go★ 9,968⑂ 461▲ 238 stars
→
5

Tencent / LoopForge

Go★ 2,110⑂ 331▲ 423 stars
→
6

HuskerMinion / techo5

Go★ 709⑂ 119▲ 22 stars
→
7

jackfrued / Python-100-Days

Jupyter Notebook★ 187,858⑂ 55,713▲ 23 stars
→
8

microsoft / generative-ai-for-beginners

Jupyter Notebook★ 123,650⑂ 66,506▲ 99 stars
→

More Trending Repositories