How to Use Google AX: Open-Source AI Agent Orchestration Runtime Installation and Development Tutorial

Symptom: an Agent can run commands, but you cannot tell what owns its workspace, network access, or failures.
Fastest fix: use the Google AX Quickstart to trace one task through its workspace and runner, then verify isolation and observability before expanding beyond a local trial.

This guide is for Go developers building Agent task executors, platform and SRE teams defining execution boundaries, and technical leads comparing local and remote development environments.

Before Google AX installation and deployment, define the runtime boundary

Treat AX as an orchestration runtime, not as a model and not as a ready-made business Agent. Its documented role is to coordinate tasks and workspaces and provide a path to run and observe task execution. Your Agent program supplies the behavior; the underlying model supplies inference. Those are separate parts of the system, even when a workflow makes them look like one product.

The distinction changes what you need to evaluate. AX may provide interfaces for describing work and connecting execution, but that does not automatically mean your deployment has a hardened sandbox, restricted egress, durable logs, or production-ready recovery. The official concepts documentation is the place to check how the project names its core objects. Use those terms consistently in your own design notes so that “task,” “workspace,” and “runner” do not become vague labels for unrelated processes.

A useful mental model is:

• Task: the work request and the information the runtime uses to initiate execution.
• Workspace: the working context prepared for that task, including the files and resources the task can access.
• Runner: the execution-side component that receives work and starts the relevant commands or Agent process.
• Agent program and model: the logic and inference components selected by you; they are not interchangeable with the runtime.

Confirm each boundary against the current project concepts and the runner documentation. Do not infer that a task object itself enforces file permissions or that a runner automatically isolates processes. Those properties depend on the documented implementation and the configuration of the environment in which you run it.

This is also where Google AX differs from a single-process Agent script. A script may be enough for a local experiment, but a runtime becomes relevant when you need a defined handoff between task input, workspace preparation, execution, and observation. That handoff is useful only if you can explain what happens when preparation fails, a command exits unsuccessfully, or a task attempts to access something outside its intended workspace.

How do you prepare a workspace and run the Google AX Quickstart?

Start by checking the current Quickstart and repository instructions rather than copying a setup command from an old note. The official project repository and Quickstart are the source of truth for the current Go toolchain requirements, dependencies, build instructions, and first-run procedure. The available material can change; do not assume a particular Go version or install command unless the current instructions say so.

Use this preparation sequence:

1. Read the repository’s setup requirements. Confirm the Go toolchain and any other dependencies named in the current instructions. If your machine does not meet a stated requirement, resolve that first instead of troubleshooting a failed build as if it were an AX issue.
2. Clone the official repository and enter its working directory. Use the repository URL linked above. Keep the checkout separate from any application repository you plan to use for testing.
3. Inspect the Quickstart before running commands. Follow its current build and launch instructions exactly. Avoid substituting a guessed executable name or package path; a guessed command can hide whether you are following a supported path.
4. Review the sample task. Open the official task example and identify its inputs, task description, and any referenced workspace or execution settings. Treat the sample as a demonstration, not as a complete policy for your own environment.
5. Run the documented minimal task and record its outcome. Note what the Quickstart says to run, what task input it uses, which workspace is prepared, and where the result or failure becomes visible. Save the exact command and output in your test notes.
6. Repeat with a controlled change. Change one harmless input or task field supported by the example, then compare the observed result. This tells you whether the value you changed reaches the execution path you expect.

The task lifecycle matters more than merely seeing a successful command. Track the sequence from input, to workspace preparation, to command execution, to returned result or visible failure. If the sample creates or selects files, check which directory contains them and whether they persist after the task ends. If a run fails, record whether the failure appears during preparation, runner startup, command execution, or result collection.

The manifest field reference can help you understand the supported configuration fields. Use it to distinguish a documented field from a local convention. If a field is not described there or in the current example, do not add it on the assumption that a familiar name will be recognized.

Important: A successful Quickstart proves that the documented example works in your development environment. It does not prove that untrusted tasks are isolated, outbound traffic is restricted, or execution can recover safely after a host failure.

A realistic developer scenario is a Go engineer testing an Agent that edits files before running a build. For the first trial, use a disposable checkout and a task with a small, inspectable change. Compare the requested change with the files actually modified. This catches a common integration error: the Agent may receive the right instruction while the runner uses a different working directory from the one the developer inspects.

How does the runner connect your custom Agent?

Use the runner documentation to identify the actual extension point before writing an adapter. The runner guide describes the documented relationship between the control side, task information, workspace, and execution. Build your integration around those interfaces; do not assume an undocumented callback, transport, or lifecycle hook exists.

A practical integration pass looks like this:

1. Define the task contract. List the inputs your Agent needs and separate them from environment settings. Keep credentials and policy decisions out of free-form task text.
2. Map task data to workspace preparation. Identify which component creates, selects, or populates the working area. Confirm what your Agent sees as its current directory and how it receives input files.
3. Connect the runner to the Agent command. Use the documented runner entry point and the execution method supported by the current guide. Keep the Agent invocation small at first: one known task, one known workspace, and a result that can be inspected.
4. Make completion and failure distinguishable. Verify how your integration reports command exit status, preparation errors, and other failures. A user-facing “task failed” message is not enough if operators cannot locate the failing stage.
5. Add observability at the boundary. Record task identity, lifecycle stage, command outcome, and relevant timestamps according to your data-retention policy. Do not log secrets, private file contents, or full prompts by default.
6. Test the adapter with a controlled failure. Use an invalid input or another safe failure supported by your test setup. Confirm that the result is visible to both the caller and the operator, and that the workspace can be inspected or removed as intended.

This approach keeps the adapter narrow. The runtime should coordinate its documented task and execution interfaces; your integration should handle the Agent-specific command and input contract. If the adapter also quietly chooses credentials, opens network access, and manages long-term state, it has become a second control plane. Separate those responsibilities so you can test and audit them independently.

Do not equate “a command started” with “the custom Agent is correctly attached.” Verify that the expected task reached the expected runner, that the runner used the expected workspace, and that the returned outcome corresponds to the process that actually ran. These checks are especially important if you later add a queue or multiple workers: an incorrect mapping can turn a clean local test into a cross-task data exposure.

Which sandbox and network boundaries must you verify?

Start with what the project documents, then test what your environment actually enforces. The sandbox documentation describes AX-related sandbox behavior; the networking documentation describes network configuration. Read both before choosing a deployment design. A documented capability is not proof that your specific runner, host, or network policy has enabled it.

Check these boundaries separately:

• Process scope: Can a task start child processes, and what operating-system identity do they use? Confirm which controls come from AX and which come from your host or container configuration.
• File scope: Can the task read or write outside its intended workspace? Test with a disposable environment and non-sensitive files. Check both the Agent command and any helper process it launches.
• Network scope: Determine whether tasks can make outbound connections, which destinations are allowed, and where the policy is enforced. Do not assume a workspace boundary also limits network access.
• Credentials: Verify how the task receives access tokens or other secrets, whether they remain available to child processes, and how you revoke them after a test.
• SSH and debugging: Enable a remote shell or debugging route only when the relevant deployment explicitly provides and secures it. Check authentication, reachability, logging, and how access is removed. Do not assume AX exposes an SSH endpoint by default.
• Failure visibility: Confirm that workspace setup errors, runner startup errors, command failures, and result-delivery errors can be distinguished by an operator.

Use a disposable test workspace to attempt a file access outside its intended scope and a connection to a destination your policy should reject. The expected result should be a clear denial or a controlled failure, not an ambiguous timeout. Repeat the checks after changing the runner or host configuration; a policy that was effective in one execution mode may not carry over to another.

Also decide what “cleanup” means before you allow tasks to run concurrently. Specify who removes a workspace, what happens after an interrupted task, and whether an operator can identify which task owns leftover files. These are deployment choices unless the current AX documentation explicitly defines the behavior for your selected execution path.

Before expanding beyond one task

Do not move directly from a successful local example to a shared service. First document the baseline environment and test a single task end to end. Then repeat the workflow under the controls you intend to use: the same workspace policy, network policy, logging path, and cleanup process.

Use this acceptance checklist before a small concurrency pilot:

• [ ] The installed Go toolchain and all required dependencies match the current official setup instructions.
• [ ] You can reproduce the documented Quickstart from a clean checkout.
• [ ] You can explain how task input becomes a prepared workspace and how the runner starts execution.
• [ ] The Agent can access only the files that the test intends it to access.
• [ ] Network access follows an explicit policy, and a denied connection produces an observable result.
• [ ] Debugging or SSH access is disabled unless you have an approved, secured operational need for it.
• [ ] Operators can distinguish workspace, runner, command, and result-delivery failures.
• [ ] A failed or interrupted task has a defined cleanup and recovery path.
• [ ] Logs have an owner, a retention policy, and a rule for excluding secrets and unnecessary task content.
• [ ] You have tested whether separate tasks can see each other’s files or state in the execution mode you plan to pilot.

If any item is unchecked, keep the trial limited to disposable data and a single task at a time. Increase concurrency only after you know how workspaces are separated, how failures are surfaced, and how abandoned work is cleaned up. Do not treat a larger worker count as an operational improvement if you cannot trace which task wrote a file or caused a network request.

These options are not interchangeable. The runtime’s control flow does not decide whether your team needs a Mac, a Linux host, or a local machine. Choose the environment from your development dependencies and operational controls, then validate that the runner behaves as expected there.

For a remote setup, first review the available infrastructure overview and the support resources relevant to your access and environment questions. If you need a temporary Mac for development or compatibility checks, Kvmjet’s Silicon Valley Mac nodes are one option to assess. Renting a Mac can avoid preparing a separate physical workstation and make a remote development environment available when you need it; it does not replace AX’s sandbox, network, or recovery controls. If you already have a suitable Mac, a stable local workload, or a requirement for hardware interfaces that a remote environment cannot provide, keeping the work on your own machine may be the better choice.

Last updated September 25, 2026. The setup and runtime boundaries in this guide were checked against the official Google AX repository and Quickstart, concepts, runner, manifest, sandbox, and networking documentation. Check those sources again before adopting an interface or security behavior in a deployment; repository examples do not establish that every deployment shape is production-validated.