First-principles learning notes for google/ax Google's declarative orchestrator for sandboxed agent workloads on Agent Substrate.
Built for Kubernetes-fluent engineers and architects teaching juniors: map AX objects and control-plane paths to familiar k8s mental models, then show where the analogy breaks.
| This repo is | This repo is not |
|---|---|
Original teaching material and verified path cites into google/ax |
A fork or mirror of upstream AX |
A curriculum under learn/ (twelve subject teach-kits) |
Runtime code you deploy as AX |
| Notes tagged Confident / Likely / Unknown against real Go/proto/deploy paths | Marketing docs or an official Google product guide |
Upstream source of truth: google/ax. Re-verify cited paths when upstream moves.
- Skim this page - especially the architecture diagram and reading paths below.
- Open the curriculum index:
learn/README.md. - Orient with the map:
learn/ax-subjects/00-map/(happy-path poster + mermaid). - Pick a path:
- Architects: 00 → 05 → 08 → 11, then deepen 01 - 04 / 06 - 07 / 09 - 10 as needed.
- Juniors: follow 00 → 01 → 05 → 08 → 06 → 02 - 04 → 07 → 09 → 10, keep 11 open as the drift log.
- For each subject: speak Say this first, contrast the Kubernetes analogy with Where it breaks, walk the diagram, then do the Junior exercise.
No live AX cluster is required for most exercises - file reads and upstream GitHub raw links are enough.
AX is a Redis-backed gRPC control plane. Agent Substrate runs the sandboxes. Failure domains are split: ax-system vs ate-system.
flowchart TB
subgraph ax_cp["AX control plane - ax-system"]
CLI["ax CLI"]
SRV["ax-server :8080 gRPC"]
REDIS[(Redis hashes + streams + pubsub)]
CTL["ax-controller workers"]
CLI --> SRV --> REDIS
REDIS --> CTL
end
subgraph sub["Agent Substrate - ate-system"]
API["Control API"]
ACT["Actor = task name"]
RTR["atenet-router"]
WRK["Worker :80 - ax-task-runner"]
API --> ACT
RTR --> WRK
end
CTL -->|"Create/Update actor, egress, suspend"| API
CLI -.->|"ssh / traffic via atenet"| RTR
Two planes at a glance:
Control-plane stream flow (apply → Redis → workers):
Happy path poster (map subject):
| Order | Subject | Why |
|---|---|---|
| 1 | 00-map | Whole-system picture |
| 2 | 05-control-plane | Redis streams, reconciliation, no CRDs |
| 3 | 08-substrate | Boundary and split failure domains |
| 4 | 11-doc-vs-code | Drift register - trust code over prose |
| 5+ | 01 - 04, 06 - 07, 09 - 10 | Depth on primitives, runner, networking, ops |
| Order | Subject | Focus |
|---|---|---|
| 1 | 00-map | Orientation |
| 2 | 01-task | Isolated execution unit |
| 3 | 05-control-plane | How apply becomes work |
| 4 | 08-substrate | What AX does not run |
| 5 | 06-runner-sandbox | PID1 contract on :80 |
| 6 | 02 · 03 · 04 | Workspace, Gateway, Model |
| 7 | 07-networking-atenet | Header routing, not Services |
| 8 | 09-cli-ops · 10-scale | Ops and failure modes |
| always | 11-doc-vs-code | Living mismatch log |
Full index, session shape, and confidence legend: learn/README.md.
| # | Topic |
|---|---|
| 00 | Map - index & k8s mental-model |
| 01 | Task |
| 02 | Workspace |
| 03 | Gateway |
| 04 | Model |
| 05 | Control plane |
| 06 | Runner / sandbox |
| 07 | Networking (atenet) |
| 08 | Agent Substrate boundary |
| 09 | CLI & ops |
| 10 | Scale & failure modes |
| 11 | Doc vs code drift |
| Asset | Subject |
|---|---|
| happy-path.png | 00-map |
| maiden-checklist.png | 02-workspace |
| model-vs-secret.png | 04-model |
| stream-flow.gif | 05-control-plane |
| two-planes.png | 08-substrate |
| amplification.png | 10-scale |
| traffic-light.png | 11-doc-vs-code |
Teaching content in this repository is original material by the owner, licensed under MIT. It is not a copy of the google/ax license or source tree. Upstream AX remains under its own license at google/ax.
- Sushant (@sushant24-ai) - curriculum author and maintainer