# warpdotdev/oz-agent-worker architecture

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

- Interactive diagram: https://gitdiagram.com/warpdotdev/oz-agent-worker
- Repository: https://github.com/warpdotdev/oz-agent-worker

## Overview

oz-agent-worker is a self-hosted daemon that receives cloud-agent assignments from Oz over WebSocket and runs them on operator-managed infrastructure. Its principal flow is startup configuration, server connection and assignment handling, backend execution, then task status/log reporting; Docker, Direct, Kubernetes, and Command are alternative execution modes, not sequential stages. The README also documents image remapping, one-shot Direct workers, and task telemetry. Edges are limited to README statements and shown source/index references; some backend wiring and unsampled subsystem links are therefore omitted.

Main entry points: [`internal/worker/worker.go`](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/worker.go) (Worker lifecycle), [`internal/worker/backend.go`](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/backend.go) (Backend selection), [`main.go`](https://github.com/warpdotdev/oz-agent-worker/blob/main/main.go) (Worker entrypoint), [`internal/tasktelemetry/otlp/exporter.go`](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/tasktelemetry/otlp/exporter.go) (OTLP export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup"]
  node_main["Worker entrypoint<br/>[main.go]"]
  node_config["Config loading<br/>[config.go]"]
end

subgraph group_coordination["Task coordination"]
  node_worker["Worker lifecycle<br/>[worker.go]"]
  node_messages["Task protocol<br/>[messages.go]"]
end

subgraph group_execution["Execution backends"]
  node_backend["Backend selection<br/>[backend.go]"]
  node_docker["Docker execution<br/>[docker.go]"]
  node_direct["Direct execution<br/>[direct.go]"]
  node_kubernetes["Kubernetes execution<br/>[kubernetes.go]"]
  node_command["Command execution<br/>[command.go]"]
  node_taskargs["Task argument building<br/>[task_utils.go]"]
  node_image_remap["Image remapping<br/>[image_remapping.go]"]
end

subgraph group_telemetry["Task telemetry"]
  node_metrics["Worker metrics<br/>[metrics.go]"]
  node_tasklogs["Task log reporting<br/>[reporter.go]"]
  node_tracing["Task tracing<br/>[session.go]"]
  node_otlp["OTLP export<br/>[exporter.go]"]
end

node_operator(("Operator"))
node_ozserver(("Oz server"))
node_collector(("Telemetry collector"))

node_operator -->|"configures"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"starts"| node_worker
node_worker -->|"connects by WebSocket"| node_ozserver
node_ozserver -->|"assigns tasks"| node_worker
node_worker -->|"handles messages"| node_messages
node_worker -.->|"selects backend"| node_backend
node_backend -.->|"dispatches execution"| node_docker
node_backend -.->|"dispatches execution"| node_direct
node_backend -.->|"dispatches execution"| node_kubernetes
node_backend -.->|"dispatches execution"| node_command
node_direct -->|"uses arguments"| node_taskargs
node_docker -->|"remaps images"| node_image_remap
node_kubernetes -->|"remaps images"| node_image_remap
node_worker -->|"records task metrics"| node_metrics
node_worker -.->|"reports task logs"| node_tasklogs
node_worker -->|"starts task traces"| node_tracing
node_tracing -->|"creates exporter"| node_otlp
node_tasklogs -->|"creates exporter"| node_otlp
node_otlp -->|"exports telemetry"| node_collector
node_worker -->|"reports task status"| node_ozserver

click node_main "https://github.com/warpdotdev/oz-agent-worker/blob/main/main.go"
click node_config "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/config/config.go"
click node_worker "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/worker.go"
click node_messages "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/types/messages.go"
click node_backend "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/backend.go"
click node_docker "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/docker.go"
click node_direct "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/direct.go"
click node_kubernetes "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/kubernetes.go"
click node_command "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/command.go"
click node_taskargs "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/common/task_utils.go"
click node_image_remap "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/common/image_remapping.go"
click node_metrics "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/metrics/metrics.go"
click node_tasklogs "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/tasktelemetry/log/reporter.go"
click node_tracing "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/tasktelemetry/tracing/session.go"
click node_otlp "https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/tasktelemetry/otlp/exporter.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_main,node_config toneBlue
class node_worker,node_messages toneAmber
class node_backend,node_docker,node_direct,node_kubernetes,node_command,node_taskargs,node_image_remap,node_ozserver toneMint
class node_metrics,node_tasklogs,node_tracing,node_otlp toneRose
class node_operator,node_collector toneIndigo
```

## Components

### Startup

- [Worker entrypoint](https://github.com/warpdotdev/oz-agent-worker/blob/main/main.go): `main.go`
- [Config loading](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/config/config.go): `internal/config/config.go`

### Task coordination

- [Worker lifecycle](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [Task protocol](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/types/messages.go): `internal/types/messages.go`

### Execution backends

- [Backend selection](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/backend.go): `internal/worker/backend.go`
- [Docker execution](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/docker.go): `internal/worker/docker.go`
- [Direct execution](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/direct.go): `internal/worker/direct.go`
- [Kubernetes execution](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/kubernetes.go): `internal/worker/kubernetes.go`
- [Command execution](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/worker/command.go): `internal/worker/command.go`
- [Task argument building](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/common/task_utils.go): `internal/common/task_utils.go`
- [Image remapping](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/common/image_remapping.go): `internal/common/image_remapping.go`

### Task telemetry

- [Worker metrics](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`
- [Task log reporting](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/tasktelemetry/log/reporter.go): `internal/tasktelemetry/log/reporter.go`
- [Task tracing](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/tasktelemetry/tracing/session.go): `internal/tasktelemetry/tracing/session.go`
- [OTLP export](https://github.com/warpdotdev/oz-agent-worker/blob/main/internal/tasktelemetry/otlp/exporter.go): `internal/tasktelemetry/otlp/exporter.go`

### Other components

- **Operator**
- **Oz server**
- **Telemetry collector**

## Connections

- Operator → Worker entrypoint: configures (evidence: `README.md`)
- Worker entrypoint → Config loading: loads settings (evidence: `main.go`)
- Worker entrypoint → Worker lifecycle: starts (evidence: `main.go`)
- Worker lifecycle → Oz server: connects by WebSocket (evidence: `README.md`)
- Oz server → Worker lifecycle: assigns tasks (evidence: `README.md`)
- Worker lifecycle → Task protocol: handles messages (evidence: `internal/worker/worker.go`)
- Worker lifecycle → Backend selection: selects backend
- Backend selection → Docker execution: dispatches execution
- Backend selection → Direct execution: dispatches execution
- Backend selection → Kubernetes execution: dispatches execution
- Backend selection → Command execution: dispatches execution
- Direct execution → Task argument building: uses arguments (evidence: `internal/common/task_utils.go`)
- Docker execution → Image remapping: remaps images (evidence: `README.md`)
- Kubernetes execution → Image remapping: remaps images (evidence: `README.md`)
- Worker lifecycle → Worker metrics: records task metrics (evidence: `internal/worker/worker.go`)
- Worker lifecycle → Task log reporting: reports task logs
- Worker lifecycle → Task tracing: starts task traces (evidence: `internal/worker/worker.go`)
- Task tracing → OTLP export: creates exporter (evidence: `internal/tasktelemetry/tracing/session.go`)
- Task log reporting → OTLP export: creates exporter (evidence: `internal/tasktelemetry/log/reporter.go`)
- OTLP export → Telemetry collector: exports telemetry (evidence: `internal/tasktelemetry/otlp/exporter.go`)
- Worker lifecycle → Oz server: reports task status (evidence: `internal/worker/worker.go`)
