01
Overview
Google Agent Executor (AX) can be self-hosted, but the current v0.3.0-era setup is infrastructure-oriented rather than a one-command desktop install. The official quick start expects a Kubernetes environment and Agent Substrate.
02
Before you install AX
The current official repository lists these deployment prerequisites: a Kubernetes cluster, Go for installing the CLI, ko for building/deploying images, a container registry your cluster can pull from, and a reachable Agent Substrate Control API.
AX is still in active early development. Treat this guide as a map of the official workflow, and verify commands against the repository before running them in production.
03
1. Install the AX CLI
The official repository currently documents:
`bash
go install github.com/google/ax/cmd/ax@latest
`
The binary is installed under your Go path. Make sure $(go env GOPATH)/bin is on your shell PATH.
04
2. Prepare Kubernetes and Agent Substrate
AX does not run its distributed control plane in isolation. Its current architecture runs on Agent Substrate. You therefore need a Kubernetes cluster plus a reachable Agent Substrate Control API.
The repository's in-cluster example uses an Agent Substrate endpoint in the cluster. Do not copy an endpoint blindly into a different environment; use the address appropriate to your deployment.
05
3. Configure a registry and `ko`
AX uses ko in its documented deployment workflow. Your target Kubernetes cluster must be able to pull images from the registry you select.
The official README currently uses a deployment command shaped like:
`bash
make deploy AX_IMAGE_REPO=<your-registry>
`
According to the repository, this deploys Redis and builds/deploys the AX control-plane images into the ax-system namespace.
06
4. Understand the manifest before running a task
AX uses Kubernetes-style ax.io/v1alpha1 resources. A practical task can combine several resources in one multi-document YAML file.
The four important kinds are:
- <strong>Task</strong> — the isolated workload.
- <strong>Workspace</strong> — Git repos, MCP servers, skills and environment preparation.
- <strong>Gateway</strong> — allowed network destinations and network policy.
- <strong>Model</strong> — model/provider configuration and credentials.
This separation is useful because an agent's code, environment, network permissions and model settings can be managed independently.
07
5. Apply a task
The repository includes an example manifest. The documented lifecycle begins with:
`bash
ax apply -f examples/task.yaml
ax get tasks
`
Use the repository's current example as your starting point rather than inventing fields from older AX versions. v0.3.0 is a substantial architectural change and the API is still v1alpha1.
08
6. Watch what the task is doing
AX provides a watch command for task phase and condition changes:
`bash
ax watch task <task-name>
`
For deeper inspection, ax describe task <task-name> returns human-readable details, while ax get task <task-name> can expose the full spec and live status.
09
7. Debug with SSH
When a Task enables debug mode, AX documents an SSH-style command into its sandbox:
`bash
ax ssh <task-name>
`
You can also execute a one-off command, such as listing the workspace. Debug access should be enabled deliberately rather than assumed as a production default.
10
8. Suspend and resume an agent
Agent workloads often wait for model responses, tools or human approval. AX exposes agent-specific lifecycle commands:
`bash
ax suspend task <task-name>
ax resume task <task-name>
`
The project positions suspend/resume as a way to checkpoint idle state and continue later. Its performance claims should remain project-attributed until independently measured in your own environment.
11
9. Lock down network access with Gateway
Do not give an autonomous task unrestricted egress simply because the example environment works. Gateway resources are designed to define outbound hosts and ports. Use the smallest allowlist your agent actually needs.
Credentials and model access deserve the same treatment. The Model resource can centralize model configuration and use Kubernetes secrets, but teams remain responsible for secret handling and least privilege.
12
10. Prepare workspaces deliberately
Workspace can pre-wire Git repositories, MCP servers and skills. AX also advertises generative workspace setup from a goal description. For reproducible production systems, record and review what the generated environment installs rather than treating generated setup as inherently trusted.
13
Troubleshooting checklist
If a Task does not start, verify the active Kubernetes context, AX control-plane reachability, Agent Substrate endpoint, registry pull permissions, deployed namespace/components and the validity of your current v1alpha1 manifest.
If ax ssh fails, confirm the Task was created with debugging enabled. If an agent cannot reach an external API, inspect Gateway policy before assuming the model or tool is broken.
14
What not to assume
AX is not currently a stable managed SaaS with a fixed monthly price. It is open-source infrastructure. The official project also warns that breaking changes are likely before a stable release, so pinning versions and reading release notes is safer than depending on latest for production automation.
15
Next step
After the first Task works, move from permissive examples to explicit Workspace, Gateway and Model resources, then test suspend/resume and failure recovery under the conditions your real agent will face.
Sources
Primary and supporting sources
Use the linked documentation to check current pricing, access and product behaviour. The dates above describe this article; they do not guarantee that every vendor claim remains current.