ax README

The project's README from github.com/google/ax. As one markdown file: README.md.

AX axolotl AX

[!WARNING] We are still actively refining our core concepts, protocols, and specifications. We will likely to introduce major breaking changes prior to a stable release.

Declare an agentic task with workspaces and gateway specifications. AX sandboxes it, wires up its workspace, fences its network, 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 four 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
Lock outbound traffic down to an explicit host allowlist Gateway
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

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

You need a Kubernetes cluster, ko (brew install ko), a container registry your cluster can pull from, and a reachable Agent Substrate Control API (in-cluster default: api.ate-system.svc.cluster.local:443).

make deploy AX_IMAGE_REPO=<your-registry>

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 + Gateway + 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, Gateway, 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.

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

# Gateways, workspaces, models follow the same pattern
ax get gateways
# NAME              ATESPACE   LISTENERS             EGRESS-HOSTS
# default-gateway   default    8494/gRPC,8080/HTTP   *
ax describe gateway default-gateway
ax delete gateway default-gateway

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.

ax (google/ax)

Searching Database…

13.9K ·GitHub
Ax
这是什么东西？AX 是 Google 开源的智能体编排运行时——一个声明式、高吞吐量的编排器，可以在 Kubernetes 集群里运行数十亿个自主智能体工作负载，每个任务都在独立沙箱中运行，并对其网络访问做隔离管控。
它是一个要加到我智能体代码里的库，还是需要部署的东西？都不是：你要把一个控制平面部署到自己的 Kubernetes 集群里，然后用一个叫 ax 的、用法类似 kubectl 的命令行工具来操作它。你要运行的一切都写成 ax.io/v1alpha1 YAML 清单，一条命令就能应用。
怎么把它跑起来？先用 go install 安装 ax CLI，再用 ko 部署控制平面，然后应用你的第一个任务。你需要一个 Kubernetes 集群、一个集群能拉取镜像的容器仓库，以及一个可以访问的 Agent Substrate Control API；./demo.sh 完整演示了整个生命周期。
在上面做开发之前有什么要注意的吗？它还不稳定：核心概念、协议和规范仍在打磨之中，在正式稳定版发布之前预计会有大的破坏性变更。如果现在就采用，要做好应对频繁变动的准备。
ax CLI 能在我的笔记本电脑上运行吗，还是只能在集群里用？CLI 是一个本地的 Go 二进制文件——go install 会把它装到 $(go env GOPATH)/bin——它通过 gRPC 和控制平面通信，并跟随你当前激活的 kubectl context。控制平面本身则运行在你集群的 ax-system 命名空间里。
AX 的四个核心原语是什么？Task 在有 CPU 和内存限制的隔离沙箱里运行不受信任的智能体代码；Workspace 预先接好 Git 仓库、MCP 服务器和技能包，让每个智能体一启动就是热状态；Gateway 把出站流量限制在明确的主机允许列表内；Model 配置平台自身使用哪个 LLM，凭据来自 Kubernetes secret。
为什么不直接在普通的 Kubernetes 上跑智能体？因为智能体既不是无状态的微服务，也不是跑完即止的批处理任务：它们会不断积累状态，需要严格的隔离，要调用模型 API 和工具服务器，而且如果没人盯着，可能会在死循环里烧掉大量钱。AX 的四个原语用声明式的方式把这些问题全都处理了。
怎么查看或暂停一个正在运行的智能体？这个 CLI 刻意做成了 kubectl 的风格——apply、get、describe、watch、delete——另外还有智能体专属的命令：ax suspend 暂停一个空闲的智能体，ax resume 从上次停下的地方原样继续，ax ssh 可以进入一个正在运行的智能体，看看它在干什么。
Agent Substrate 是什么？默认的运行器可以替换吗？Agent Substrate 是 AX 所依赖的沙箱执行层；集群必须能访问它的 Control API（集群内默认地址：api.ate-system.svc.cluster.local:443）。可以替换——Runners 指南说明了控制平面的契约，你可以构建自己的运行器镜像来替换默认的那个。
What are similar projects?substrate, trueforge, go-micro, ruflo, evenfire, dapr, serve, AgentTeams
Which topics is it in?scalability, grpc, google, sandbox, orchestration, agent-orchestration, distributed-systems, kubernetes, cloud, devops, go, agent
Creator
google
Size
44.1 MB
Stars
13.9K
Updated
CommitOct 16Releasev0.3.1Sep 25
Age
6mo
Commits · 90 Days