AX

警告

我们仍在积极完善核心概念、协议和规范。在稳定版本发布前，我们很可能会引入重大的破坏性变更。

使用工作空间和网关规范声明一项智能体任务。AX 会将其置于沙箱中，连接其工作空间，限制其网络，并帮助其大规模运行。

AX 是一个高吞吐量的声明式编排器，可在集群中运行数十亿个自主 Agent 工作负载。它构建于 Agent Substrate 之上，用于提供沙箱化执行，并且旨在让每个集群运行数十亿项任务。如果你使用过 Kubernetes，ax 会让你感到很熟悉。

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

然后应用配置，观察其启动，并查看 Agent 正在做什么：

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

Agent 是一种新型工作负载。它们既不是无状态微服务，也不是运行至完成的批处理作业。它们会积累状态，需要严格隔离，需要调用模型 API 和工具服务器；如果无人监控，还可能在循环中持续烧钱。AX 提供了四个小型原语，以声明式方式处理这些需求：

你希望……	AX 提供
在具备 CPU/内存限制的隔离沙箱中运行不可信 Agent 代码	Task
预先连接 Git 仓库、MCP 服务器和技能包，让每个 Agent 都能以预热状态启动	Workspace
将出站流量限制为明确指定的主机允许列表	Gateway
使用 Kubernetes Secret 中的凭据，配置平台自身所使用的 LLM	Model
暂停空闲 Agent，并从其停止的位置精确继续执行	ax suspend / ax resume
进入正在运行的 Agent Shell，以查看其正在执行的操作	ax ssh

所有内容都通过 ax.io/v1alpha1 Manifest 表达，并通过单条命令应用。

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

这会将 ax 二进制文件放置到 $(go env GOPATH)/bin。请确保该目录已在你的 PATH 中。

2. 部署控制平面

你需要一个 Kubernetes 集群、ko（brew install ko）、一个集群可以拉取镜像的容器镜像仓库，以及一个可访问的 Agent Substrate Control API（集群内默认地址：api.ate-system.svc.cluster.local:443）。

make deploy AX_IMAGE_REPO=

该命令会部署 Redis，然后使用 ko 构建并部署控制平面镜像。所有组件都会部署到 ax-system 命名空间。

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

想要端到端查看完整生命周期？运行 ./demo.sh。它会应用一个自定义工作空间，等待其就绪，通过 ax ssh 运行命令，并暂停任务。

指南	阅读以……
概念	了解 Task、Workspace、Gateway 和 Model 分别承担什么作用，以及任务如何在不同阶段和条件之间流转。
Manifest	编写你自己的 YAML，其中包含每种资源类型的带注释示例。
沙箱	了解运行器启动时执行的操作，以及你的命令可以依赖的内容：元数据服务器、访客服务和环境。
运行器	理解控制平面与任务容器之间的契约，并构建自己的运行器镜像以替代默认镜像。
网络	了解如何通过 atenet 路由器，从集群、笔记本电脑或 gRPC 客户端访问正在运行的任务。
架构	理解控制平面如何组合在一起，以及查看 API 参考。
开发	构建、测试并发布对 AX 本身的修改。

ax 通过 gRPC 与控制平面通信。它刻意采用类似 kubectl 的命令形式：apply、get、describe、watch、delete，以及一些 Agent 专用动词。

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

ax 会遵循你当前激活的 Kubernetes context。切换集群后，ax 会解析该集群的控制平面，并在后台建立到该控制平面的隧道。

kubectx staging-cluster ax get tasks

kubectx prod-cluster ax get tasks

Or target a context without switching

ax --context=dev-cluster get tasks

参数	描述	默认值
-a, --atespace	命令的 Atespace 作用域	default
-n, --namespace	安装 AX 的 Kubernetes 命名空间	ax-system
--context	要定位的 Kubernetes context	当前激活的 kubectx / current-context
--server	控制平面地址，绕过自动发现	从 kube context 或 $AX_SERVER 派生

Apache License 2.0。详见 LICENSE。

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

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.

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.

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.

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.

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

# 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

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

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

Apache License 2.0. See LICENSE for details.