The Problem

Running autonomous agents in production requires isolated execution, controlled networking, and a declarative way to specify workspaces, toolchains, and model access. Existing solutions treat agents as either stateless services or batch jobs, making it hard to enforce per‑task resource limits, persist state, or audit outbound traffic.

What This Does

ax is a declarative orchestrator that runs tasks in isolated sandboxes, wires up git workspaces, fences networks, and manages LLM credentials—all expressed as ax.io/v1alpha1 manifests. The control plane is built in Go and exposes a ax CLI (cmd/ax/main.go) that forwards apply, watch, ssh, suspend, and resume commands to the controller (cmd/ax-controller/main.go) or the task runner (cmd/ax-task-runner/main.go). The runtime leverages Agent Substrate (internal/substrate/client.go) for sandboxed execution and uses Redis (internal/store/redis/store.go) or an in‑memory fallback (internal/store/memory/store.go) to keep task state.

How It Is Wired

Entry Point – cmd/ax/main.go parses the CLI and dispatches to subcommands.

  • apply → internal/controller/Reconciler.Reconcile (file internal/controller/reconciler.go) which creates or updates Kubernetes‑style CRDs (pkg/apis/v1alpha1/ax.proto).
  • watch → internal/controller/Reconciler streams status updates via the gRPC API served by cmd/ax-controller/main.go.
  • ssh, suspend, resume → internal/guest/client.go talks to the task runner over a local socket, which in turn calls internal/workspace/Planner to prepare the sandbox and internal/substrate/client to launch the agent inside the container defined by Dockerfile.task-runner.

The task runner (cmd/ax-task-runner/main.go) implements a lightweight HTTP server that receives execution requests, marshals the workspace into /workspace, and runs the agent code with CPU/memory limits taken from the CRD.

What This Code Touches Outside Itself –

  • Stores data in Redis or memory (internal/store/*.go).
  • Issues gRPC calls to the controller (cmd/ax-controller/main.go).
  • Spawns Docker containers for the sandbox (Dockerfile.task-runner).

What Each File Is Responsible For –

  • cmd/ax/main.go: CLI entry point, command routing.
  • cmd/ax-controller/main.go: Starts the controller gRPC server.
  • cmd/ax-server/main.go: Runs the public API server (HTTP/REST).
  • internal/controller/reconciler.go: Reconciliation loop that watches CRDs and triggers task creation.
  • internal/guest/client.go: Client for the sandbox process, handles ssh and control commands.
  • internal/substrate/client.go: Thin wrapper over Agent Substrate API.
  • internal/workspace/planner.go: Clones git repos, arranges volumes, and writes the sandbox spec.
  • internal/store/*.go: Persistence layer for task status.

The graph contains no cycles beyond the standard controller-runtime pattern; the heaviest coupling is between the reconciler and the guest client, which is intentional to keep the control plane stateless.

How To Use It

Setup – Clone and build the control plane.

git clone https://github.com/moses-y/ax
cd ax
make deploy AX_IMAGE_REPO=<your-registry>

make deploy pulls Redis, builds controller images with ko, and applies the manifests in deploy/. Configuration – The only external config is the Kubernetes secret that holds LLM credentials; no hard‑coded keys appear in the repo. Running – After the control plane is running, apply a task manifest.

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

The examples/task.yaml file contains a Workspace, a Task, a Gateway, and a Model.

Real-World Use

A CI/CD pipeline that builds a new Go release could push a Task that pulls the repo, compiles the binaries, and runs unit tests inside a sandbox, ensuring no tampering with host resources.

apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: build-test
spec:
  workspaces:
    - name: golang
      goal: "Build and test the Go project"
  debug: false

Code Health & Issues

  • Tests – 10 test files covering controller, worker, metadata, and workspace logic.
  • CI – GitHub Actions workflows (.github/workflows/go.yml and check-binaries.yml) run go test ./... on every push.
  • Dependencies – Managed via Go modules (go.mod).
  • License – Apache‑2.0 (file LICENSE).
  • Missing – No integration tests against a real Kubernetes cluster; the demo.sh script demonstrates usage but no automated end‑to‑end verification.

The Bottom Line

ax provides a focused, Kubernetes‑style orchestrator for autonomous agents, with clear separation between controller, sandbox, and storage. It is production‑ready for environments that already run Kubernetes and can tolerate an evolving API surface. For teams needing isolated, stateful agent workloads at scale, ax offers a solid foundation that can be extended with custom workspaces or gateways.