# openai/orchard architecture

> Architecture diagram of the GitHub repository openai/orchard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/orchard
- Repository: https://github.com/openai/orchard

## Overview

Orchard orchestrates Tart-backed VM clusters: users operate a cluster through the CLI or REST API, while workers register with the controller and manage assigned VMs. The graph separates client access, controller coordination and persistence, and worker-side VM execution. The README documents local development mode and cluster management; several API and worker subsystems are represented by their exact directories because their implementation files were not sampled.

Main entry points: [`internal/worker/worker.go`](https://github.com/openai/orchard/blob/main/internal/worker/worker.go) (Worker agent), [`pkg/client/client.go`](https://github.com/openai/orchard/blob/main/pkg/client/client.go) (Go client), [`internal/controller/controller.go`](https://github.com/openai/orchard/blob/main/internal/controller/controller.go) (Controller), [`internal/command`](https://github.com/openai/orchard/tree/main/internal/command) (Orchard CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User access"]
  node_cli["Orchard CLI"]
  node_client["Go client<br/>[client.go]"]
  node_dev["Local dev mode"]
end

subgraph group_control["Controller"]
  node_rest["REST API"]
  node_controller["Controller<br/>[controller.go]"]
  node_scheduler["VM scheduler"]
  node_store[("Badger store")]
end

subgraph group_execution["Worker execution"]
  node_worker["Worker agent<br/>[worker.go]"]
  node_vmmanager["VM manager<br/>[vmmanager.go]"]
  node_runtimes["VM runtimes"]
  node_tart["Tart runtime<br/>[tart.go]"]
end

subgraph group_domain["Cluster resources"]
  node_resources["Cluster resources"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"uses API"| node_client
node_client -->|"sends HTTP requests"| node_rest
node_rest -.->|"routes requests"| node_controller
node_controller -->|"creates store"| node_store
node_controller -->|"starts scheduler"| node_scheduler
node_worker -->|"uses client"| node_client
node_worker -->|"manages VMs"| node_vmmanager
node_worker -->|"creates VMs"| node_runtimes
node_vmmanager -->|"stores VM resources"| node_resources
node_worker -->|"updates cluster state"| node_resources
node_dev -->|"starts local cluster"| node_operator
node_operator -->|"uses programmatically"| node_client
node_runtimes -.->|"includes implementation"| node_tart

click node_cli "https://github.com/openai/orchard/tree/main/internal/command"
click node_client "https://github.com/openai/orchard/blob/main/pkg/client/client.go"
click node_rest "https://github.com/openai/orchard/tree/main/internal/controller"
click node_controller "https://github.com/openai/orchard/blob/main/internal/controller/controller.go"
click node_scheduler "https://github.com/openai/orchard/tree/main/internal/controller/scheduler"
click node_store "https://github.com/openai/orchard/tree/main/internal/controller/store/badger"
click node_worker "https://github.com/openai/orchard/blob/main/internal/worker/worker.go"
click node_vmmanager "https://github.com/openai/orchard/blob/main/internal/worker/vmmanager/vmmanager.go"
click node_runtimes "https://github.com/openai/orchard/tree/main/internal/worker/runtime"
click node_tart "https://github.com/openai/orchard/blob/main/internal/worker/vmmanager/tart/tart.go"
click node_resources "https://github.com/openai/orchard/tree/main/pkg/resource/v1"
click node_dev "https://github.com/openai/orchard/tree/main/internal/command/dev"

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_client,node_dev toneBlue
class node_rest,node_controller,node_scheduler,node_store toneAmber
class node_worker,node_vmmanager,node_runtimes,node_tart toneMint
class node_resources toneRose
class node_operator toneIndigo
```

## Components

### User access

- [Orchard CLI](https://github.com/openai/orchard/tree/main/internal/command): `internal/command`
- [Go client](https://github.com/openai/orchard/blob/main/pkg/client/client.go): `pkg/client/client.go`
- [Local dev mode](https://github.com/openai/orchard/tree/main/internal/command/dev): `internal/command/dev`

### Controller

- [REST API](https://github.com/openai/orchard/tree/main/internal/controller): `internal/controller`
- [Controller](https://github.com/openai/orchard/blob/main/internal/controller/controller.go): `internal/controller/controller.go`
- [VM scheduler](https://github.com/openai/orchard/tree/main/internal/controller/scheduler): `internal/controller/scheduler`
- [Badger store](https://github.com/openai/orchard/tree/main/internal/controller/store/badger): `internal/controller/store/badger`

### Worker execution

- [Worker agent](https://github.com/openai/orchard/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [VM manager](https://github.com/openai/orchard/blob/main/internal/worker/vmmanager/vmmanager.go): `internal/worker/vmmanager/vmmanager.go`
- [VM runtimes](https://github.com/openai/orchard/tree/main/internal/worker/runtime): `internal/worker/runtime`
- [Tart runtime](https://github.com/openai/orchard/blob/main/internal/worker/vmmanager/tart/tart.go): `internal/worker/vmmanager/tart/tart.go`

### Cluster resources

- [Cluster resources](https://github.com/openai/orchard/tree/main/pkg/resource/v1): `pkg/resource/v1`

### Other components

- **Operator**

## Connections

- Operator → Orchard CLI: runs commands (evidence: `README.md`)
- Orchard CLI → Go client: uses API (evidence: `internal/command/get/worker.go`)
- Go client → REST API: sends HTTP requests (evidence: `pkg/client/client.go`)
- REST API → Controller: routes requests (evidence: `internal/controller/controller.go`)
- Controller → Badger store: creates store (evidence: `internal/controller/controller.go`)
- Controller → VM scheduler: starts scheduler (evidence: `internal/controller/controller.go`)
- Worker agent → Go client: uses client (evidence: `internal/worker/worker.go`)
- Worker agent → VM manager: manages VMs (evidence: `internal/worker/worker.go`)
- Worker agent → VM runtimes: creates VMs (evidence: `internal/worker/worker.go`)
- VM manager → Cluster resources: stores VM resources (evidence: `internal/worker/vmmanager/vmmanager.go`)
- Worker agent → Cluster resources: updates cluster state (evidence: `internal/worker/worker.go`)
- Local dev mode → Operator: starts local cluster (evidence: `README.md`)
- Operator → Go client: uses programmatically (evidence: `README.md`)
- VM runtimes → Tart runtime: includes implementation
