# tayda64/google-k8--ax architecture

> Architecture diagram of the GitHub repository tayda64/google-k8--ax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tayda64/google-k8--ax
- Repository: https://github.com/tayda64/google-k8--ax

## Overview

AX is a declarative orchestrator for sandboxed agent tasks. The main workflow is to apply Task, Workspace, Gateway, and Model manifests with the CLI; the API stores them and emits task events; controller workers reconcile tasks into Substrate actors; and the task runner prepares workspaces and serves task metadata and optional guest access. The graph also shows model configuration and SSH access. README documents additional workspace inputs and lifecycle commands; source excerpts do not establish every integration’s wiring.

Main entry points: [`cmd/ax/main.go`](https://github.com/tayda64/google-k8--ax/blob/main/cmd/ax/main.go) (AX CLI), [`internal/store`](https://github.com/tayda64/google-k8--ax/tree/main/internal/store) (Resource store), [`internal/controller/worker.go`](https://github.com/tayda64/google-k8--ax/blob/main/internal/controller/worker.go) (Task worker), [`runner/runner.go`](https://github.com/tayda64/google-k8--ax/blob/main/runner/runner.go) (Runner lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_cli["AX CLI<br/>[main.go]"]
  node_api["AX gRPC API<br/>[server.go]"]
  node_schemas["Resource API types"]
  node_store[("Resource store")]
  node_redis[("Redis backend<br/>[store.go]")]
  node_events["Task event stream"]
end

subgraph group_provision["Task provisioning"]
  node_worker["Task worker<br/>[worker.go]"]
  node_reconciler["Task reconciler<br/>[reconciler.go]"]
  node_substrate["Agent Substrate"]
  node_workspace["Workspace planner"]
  node_gateway["Gateway policy<br/>[reconciler.go]"]
end

subgraph group_runtime["Sandbox runtime"]
  node_taskrunner["Task runner entry<br/>[main.go]"]
  node_runner["Runner lifecycle<br/>[runner.go]"]
  node_metadata["Task metadata<br/>[server.go]"]
  node_guest["Guest services<br/>[client.go]"]
  node_modelclient["Model client<br/>[client.go]"]
end

subgraph group_access["Agent access"]
  node_tunnel["Cluster tunnel"]
end

node_operator(("Operator"))
node_modelapi["Google model API"]
node_agent(("Task process"))

node_operator -->|"invokes"| node_cli
node_cli -->|"encodes manifests"| node_schemas
node_cli -->|"calls gRPC"| node_api
node_api -->|"reads and writes"| node_store
node_store -->|"persists data"| node_redis
node_store -->|"publishes task events"| node_events
node_worker -->|"consumes events"| node_events
node_worker -->|"loads resources"| node_store
node_worker -->|"reconciles task"| node_reconciler
node_reconciler -->|"creates actors"| node_substrate
node_worker -->|"resolves workspaces"| node_workspace
node_reconciler -->|"applies egress policy"| node_gateway
node_substrate -->|"starts task container"| node_taskrunner
node_taskrunner -->|"runs task"| node_runner
node_runner -->|"plans workspace"| node_workspace
node_runner -->|"serves task metadata"| node_metadata
node_runner -.->|"enables debug services"| node_guest
node_agent -->|"reads metadata"| node_metadata
node_cli -->|"connects to cluster"| node_tunnel
node_cli -.->|"runs SSH commands"| node_guest
node_store -->|"loads model config"| node_modelclient
node_modelclient -.->|"generates responses"| node_modelapi

click node_cli "https://github.com/tayda64/google-k8--ax/blob/main/cmd/ax/main.go"
click node_api "https://github.com/tayda64/google-k8--ax/blob/main/internal/server/server.go"
click node_schemas "https://github.com/tayda64/google-k8--ax/tree/main/pkg/apis/v1alpha1"
click node_store "https://github.com/tayda64/google-k8--ax/tree/main/internal/store"
click node_redis "https://github.com/tayda64/google-k8--ax/blob/main/internal/store/redis/store.go"
click node_events "https://github.com/tayda64/google-k8--ax/tree/main/internal/store"
click node_worker "https://github.com/tayda64/google-k8--ax/blob/main/internal/controller/worker.go"
click node_reconciler "https://github.com/tayda64/google-k8--ax/blob/main/internal/controller/reconciler.go"
click node_workspace "https://github.com/tayda64/google-k8--ax/tree/main/internal/workspace"
click node_gateway "https://github.com/tayda64/google-k8--ax/blob/main/internal/controller/reconciler.go"
click node_taskrunner "https://github.com/tayda64/google-k8--ax/blob/main/cmd/ax-task-runner/main.go"
click node_runner "https://github.com/tayda64/google-k8--ax/blob/main/runner/runner.go"
click node_metadata "https://github.com/tayda64/google-k8--ax/blob/main/internal/metadata/server.go"
click node_guest "https://github.com/tayda64/google-k8--ax/blob/main/internal/guest/client.go"
click node_tunnel "https://github.com/tayda64/google-k8--ax/tree/main/internal/tunnel"
click node_modelclient "https://github.com/tayda64/google-k8--ax/blob/main/internal/model/client.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api,node_schemas,node_store,node_redis,node_events toneBlue
class node_worker,node_reconciler,node_substrate,node_workspace,node_gateway toneAmber
class node_taskrunner,node_runner,node_metadata,node_guest,node_modelclient,node_modelapi toneMint
class node_tunnel,node_agent toneRose
class node_operator toneIndigo
```

## Components

### Control plane

- [AX CLI](https://github.com/tayda64/google-k8--ax/blob/main/cmd/ax/main.go): `cmd/ax/main.go`
- [AX gRPC API](https://github.com/tayda64/google-k8--ax/blob/main/internal/server/server.go): `internal/server/server.go`
- [Resource API types](https://github.com/tayda64/google-k8--ax/tree/main/pkg/apis/v1alpha1): `pkg/apis/v1alpha1`
- [Resource store](https://github.com/tayda64/google-k8--ax/tree/main/internal/store): `internal/store`
- [Redis backend](https://github.com/tayda64/google-k8--ax/blob/main/internal/store/redis/store.go): `internal/store/redis/store.go`
- [Task event stream](https://github.com/tayda64/google-k8--ax/tree/main/internal/store): `internal/store`

### Task provisioning

- [Task worker](https://github.com/tayda64/google-k8--ax/blob/main/internal/controller/worker.go): `internal/controller/worker.go`
- [Task reconciler](https://github.com/tayda64/google-k8--ax/blob/main/internal/controller/reconciler.go): `internal/controller/reconciler.go`
- **Agent Substrate**
- [Workspace planner](https://github.com/tayda64/google-k8--ax/tree/main/internal/workspace): `internal/workspace`
- [Gateway policy](https://github.com/tayda64/google-k8--ax/blob/main/internal/controller/reconciler.go): `internal/controller/reconciler.go`

### Sandbox runtime

- [Task runner entry](https://github.com/tayda64/google-k8--ax/blob/main/cmd/ax-task-runner/main.go): `cmd/ax-task-runner/main.go`
- [Runner lifecycle](https://github.com/tayda64/google-k8--ax/blob/main/runner/runner.go): `runner/runner.go`
- [Task metadata](https://github.com/tayda64/google-k8--ax/blob/main/internal/metadata/server.go): `internal/metadata/server.go`
- [Guest services](https://github.com/tayda64/google-k8--ax/blob/main/internal/guest/client.go): `internal/guest/client.go`
- [Model client](https://github.com/tayda64/google-k8--ax/blob/main/internal/model/client.go): `internal/model/client.go`

### Agent access

- [Cluster tunnel](https://github.com/tayda64/google-k8--ax/tree/main/internal/tunnel): `internal/tunnel`

### Other components

- **Operator**
- **Google model API**
- **Task process**

## Connections

- Operator → AX CLI: invokes
- AX CLI → Resource API types: encodes manifests
- AX CLI → AX gRPC API: calls gRPC
- AX gRPC API → Resource store: reads and writes
- Resource store → Redis backend: persists data
- Resource store → Task event stream: publishes task events
- Task worker → Task event stream: consumes events
- Task worker → Resource store: loads resources
- Task worker → Task reconciler: reconciles task
- Task reconciler → Agent Substrate: creates actors
- Task worker → Workspace planner: resolves workspaces
- Task reconciler → Gateway policy: applies egress policy
- Agent Substrate → Task runner entry: starts task container
- Task runner entry → Runner lifecycle: runs task
- Runner lifecycle → Workspace planner: plans workspace
- Runner lifecycle → Task metadata: serves task metadata
- Runner lifecycle → Guest services: enables debug services
- Task process → Task metadata: reads metadata
- AX CLI → Cluster tunnel: connects to cluster
- AX CLI → Guest services: runs SSH commands
- Resource store → Model client: loads model config
- Model client → Google model API: generates responses