🧭 Decision Guide
Why trending now: README 突出 Agent Substrate、Kubernetes 风格 CLI、沙箱隔离以及面向 billions agent workloads 的目标;同时仓库当日新增 2,305 颗星、总星数达到 7,604,且最新版本为 v0.3.0。材料能说明这些关注点与增长信号,但无法确认具体的单一传播原因。
Try it if you
-
你已有 Kubernetes 集群、镜像仓库和 Agent Substrate Control API,想运行隔离的 Task。README 的 Quick start 要求 Kubernetes、container registry 和 reachable Agent Substrate Control API。
-
你需要把 Git 仓库、MCP 服务器或 skill 包预置到每个智能体的 Workspace。README 的 Why? 章节说明 Workspace 可预连接 Git repos、MCP servers 和 skill packages。
-
你要暂停智能体并恢复其状态,或用 ax ssh 检查运行中的沙箱。README 的 Why? 和 CLI usage 章节列出 ax suspend、ax resume 与 ax ssh。
Skip it if you
-
你没有 Kubernetes 集群、ko、可拉取镜像的 registry 或 Agent Substrate Control API。README 的 Quick start 第 2 步将这些列为部署 control plane 的前置条件。
-
你的项目要求稳定且不接受 API 或协议变化。README 顶部 WARNING 明确表示 stable release 前可能引入 major breaking changes。
-
你只需要无状态微服务或 run-to-completion batch job,而不是带状态和隔离需求的 agent workload。README 的 Why? 章节将 agents 与 stateless microservices、run-to-completion batch jobs 区分开。
Requirements
- Kubernetes 集群。
- ko;README 给出的安装示例为 brew install ko。
- 一个 Kubernetes 集群可拉取的 container registry。
- 可访问的 Agent Substrate Control API;集群内默认地址为 api.ate-system.svc.cluster.local:443。
- 部署命令会使用 Redis,并将 control plane 部署到 ax-system namespace。
- CLI 安装需要 Go,README 命令为 go install github.com/google/ax/cmd/ax@latest。
First step (verbatim from README)
go install github.com/google/ax/cmd/ax@latest
Watch out
-
ax ssh 进入任务要求 Task 设置 spec.debug: true。README 的 CLI usage 说明 interactive shell 需要 task 的 spec.debug: true。
-
ax apply 依赖 ax.io/v1alpha1 清单格式和 control plane 连接。README 说明资源使用 ax.io/v1alpha1 manifests,并通过 gRPC 与 control plane 通信。
-
跨集群操作会跟随 kubectx 当前 context,--context 可显式指定目标集群。README 的 Works with kubectx 章节和 Global flags 章节分别说明 active context 与 --context。
-
Model 的提供商与模型配置示例显示为 google 和 gemini-3.8-flash。README CLI usage 的 ax get models 示例展示 provider 为 google、model 为 gemini-3.8-flash。
Not stated in the README
- README 未说明支持的 Kubernetes 版本范围。
- README 未给出 Agent Substrate 的部署步骤、版本要求或兼容矩阵。
- README 未量化 billions of tasks per cluster 的吞吐、延迟或资源消耗。
- README 未说明 Task 的 CPU/memory limits 如何配置及其默认值。
- README 未说明 Gateway 主机允许列表的完整配置语法和默认安全行为。
- README 未说明 Google Gemini 之外支持哪些 Model provider。
- README 未说明 control plane 的认证、授权、TLS 和多租户隔离细节。
- README 未说明 Redis 的高可用、持久化和故障恢复配置。
- README 未说明 v0.3.0 与 ax.io/v1alpha1 的稳定性或升级迁移策略。
💡 Deep Analysis
6
No
I need to switch between staging and production Kubernetes clusters and bring agent tasks into production operations. Given that the project is v0.3.0 with a v1alpha1 API, is AX suitable as a stable production interface now?
No, not as a stable production interface today, because the README explicitly warns that the core concepts, protocols, and specifications may undergo major breaking changes.
- The warning says, “We will likely to introduce major breaking changes prior to a stable release,” and the API examples use
ax.io/v1alpha1. - Project data lists v0.3.0 as the latest release and only 5 releases, indicating an early-stage project.
- AX does provide basic multi-cluster operations through Kubernetes contexts, with examples for staging, prod, and
--context=dev-cluster. - However, the README provides no upgrade migration policy, compatibility matrix, stability guarantee, or production SLA. If the production interface must remain compatible over time, the current risk outweighs the operational convenience.
- README warning: “We are still actively refining our core concepts, protocols, and specifications”
- README warning: “We will likely to introduce major breaking changes prior to a stable release”
- Project data: latest version v0.3.0 with 5 releases
- Works with kubectx: `kubectx staging-cluster`, `kubectx prod-cluster`, and `ax --context=dev-cluster get tasks`
ax version
Yes
I need a coding agent to start from the `my-fix` branch of `https://github.com/golang/go.git` and inspect `/workspace` inside the sandbox. Can AX express this initialization in one declarative submission?
Yes: the README directly demonstrates the combination of a Git workspace, a task goal, and sandbox debugging.
- Workspace can declare a Git repository and branch; the example uses
https://github.com/golang/go.gitwithmy-fix, then binds thegolangworkspace to the Task. - The Task
goalcan state “Ensure that Go tool chain is available and is built from source,” allowing workspace preparation and task intent to live in one multi-document YAML file. - With
debug: true,ax sshcan enter the sandbox; the README example usesax ssh test -- ls -al /workspaceto inspect it. - However, the README does not promise handling for private Git credentials, branch conflicts, commit pinning, or recovery semantics when MCP initialization fails.
- README YAML example: Workspace uses `repo: https://github.com/golang/go.git` and `branch: "my-fix"`
- README YAML example: Task uses `workspaces` and `goal`
- README YAML example: `debug: true`; Quick start uses `ax ssh test -- ls -al /workspace`
- Why? table: Workspace can pre-wire Git repos, MCP servers, and skill packages
ax apply -f task.yaml
It depends
I need agents to run untrusted code while allowing access only to model APIs, Git repositories, and MCP services. Can AX directly provide the sandbox and network boundary I need?
It depends: AX supplies declarative sandboxing and egress primitives, but the complete security guarantee depends on Agent Substrate and its configuration.
- Task runs untrusted agent code in an isolated sandbox with CPU and memory limits.
- Gateway restricts outbound traffic through an explicit host allowlist, which can express access to required model APIs, Git hosts, and MCP services.
- AX explicitly runs on Agent Substrate; the README does not claim that AX alone defends against kernel vulnerabilities, sandbox escapes, or high-privilege malicious code.
- The example Gateway output shows
EGRESS-HOSTS *, demonstrating that a wildcard weakens egress restriction. Model credentials come from a Kubernetes Secret, but application-level tool authorization, data redaction, and identity checks are not automatically provided by these primitives.
- Why? table: `Task` provides “Run untrusted agent code in an isolated sandbox with CPU/memory limits”
- Why? table: `Gateway` provides “Lock outbound traffic down to an explicit host allowlist”
- README introduction: “It runs on top of Agent Substrate for sandboxed execution”
- CLI usage: the Gateway example shows `EGRESS-HOSTS *`; Model uses a Kubernetes secret
make deploy AX_IMAGE_REPO=<your-registry>
Yes
I want to declare Google `gemini-3.8-flash` in Kubernetes, store credentials in a Secret, and restrict model request egress through Gateway. Does AX cover this configuration path?
Yes: AX’s Model and Gateway primitives cover the declarative model, Secret, and egress configuration path.
- The README defines Model as the LLM configuration used by the platform and explicitly says credentials come from a Kubernetes Secret.
- The
ax describe modelexample shows providergoogleand modelgemini-3.8-flash, directly matching this constraint. - Gateway controls outbound access through an explicit host allowlist, so the model service can be included in the task’s network boundary rather than encoded in agent code.
- These features establish configuration and boundary primitives only; the README does not specify Secret field names, the required Google API endpoint list, key rotation, request auditing, or retry behavior when the model is unavailable.
- Why? table: Model “Configure which LLM the platform itself uses, with credentials from a Kubernetes secret”
- CLI usage: `default-model default google gemini-3.8-flash`
- Why? table: Gateway “Lock outbound traffic down to an explicit host allowlist”
- Project data: Go is the main language; latest release is v0.3.0
ax apply -f examples/task.yaml
Yes
I want to build a custom runner image in Go and replace AX’s default task executor. Does the README provide an extension point rather than forcing use of the built-in runner?
Yes: the README explicitly exposes the Runner contract as an extension point for replacing the execution layer.
- The Runners guide is intended to explain the contract between the control plane and task container and to build a custom runner image that replaces the default.
- The control plane and CLI are primarily implemented in Go, and project data shows Go is by far the dominant language, so the developer’s language environment aligns with the project.
- The Sandbox guide documents runner boot behavior, the metadata server, guest services, and the environment available to commands, providing context for a custom image.
- However, the supplied README does not enumerate startup protocol details, health states, exit codes, signal handling, state persistence, or credential injection fields. It confirms the extension direction but is insufficient by itself for a compatible implementation.
- Documentation: Runners says to “build your own runner image to replace the default”
- Documentation: Sandbox covers the metadata server, guest services, and environment
- CLI usage: `ax` communicates with the control plane over gRPC
- Project data: Go has 299270 bytes and dominates the codebase
go install github.com/google/ax/cmd/ax@latest
It depends
I already operate a Kubernetes cluster and want a kubectl-like way to create, observe, suspend, and resume billions of agent tasks. Is AX suitable as the orchestration entry point?
It depends: AX matches the desired declarative workflow, but the README does not validate its claimed scale with operational benchmarks.
- Task, Workspace, Gateway, and Model are represented as
ax.io/v1alpha1multi-document manifests, withapply,watch,suspend, andresumecommands suitable for platform automation. - The README positions AX as a high-throughput orchestrator intended to run “billions of autonomous agent workloads” in a cluster, on top of Kubernetes and Agent Substrate.
- Multi-cluster usage follows Kubernetes contexts; the README shows switching with
kubectx staging-clusterandkubectx prod-cluster. - However, it provides no control-plane throughput, Redis capacity, fairness, recovery, or billion-task benchmark, so the stated target cannot by itself establish an SLA at that scale.
- Why?: “AX gives you four small primitives that handle all of that declaratively”
- README: “a high-throughput, declarative orchestrator to run billions of autonomous agent workloads in a cluster”
- Works with kubectx: examples using `staging-cluster` and `prod-cluster`
- Project data: Go is the main language; latest release v0.3.0 with 5 releases
ax apply -f examples/task.yaml
✨ Highlights
-
Four declarative primitives: Task, Workspace, Gateway, and Model
-
Supports checkpointing with ax suspend and ax resume
-
Uses Agent Substrate to run large-scale sandboxed tasks
-
The README warns of major breaking changes before stable release
🔧 Engineering
-
Declare Task, Workspace, Gateway, and Model resources with ax.io/v1alpha1 YAML
-
ax ssh can enter a debug sandbox and inspect /workspace
-
ax watch streams task phase and condition changes live
-
Gateway restricts agent egress with an explicit host allowlist
⚠️ Risks
-
The README warns that major breaking changes may arrive before stable release
-
Deployment requires Kubernetes, ko, a registry, and the Agent Substrate API
-
Model credentials depend on a Kubernetes Secret, with details not covered in the material
-
The README claims billions of tasks but provides no performance measurements
👥 For who?
-
Teams running isolated agent workloads in a Kubernetes cluster
-
Developers who want to manage Task lifecycles with Go or YAML
-
Agent platforms that need Git, MCP servers, and skill packages pre-wired