# metr/vivaria architecture

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

- Interactive diagram: https://gitdiagram.com/metr/vivaria
- Repository: https://github.com/metr/vivaria

## Overview

Vivaria is a web application and CLI for setting up task environments, running agents, and studying their trajectories. The main workflow spans user requests, server APIs, task/container execution, trace persistence, and run review or annotation; the playground and Inspect-log import are additional documented capabilities. The README and sampled excerpts support these broad connections, but not every route or service call, so uncertain wiring is omitted.

Main entry points: [`server/src/routes/index.ts`](https://github.com/metr/vivaria/blob/main/server/src/routes/index.ts) (API routes), [`ui/src/run/RunPage.tsx`](https://github.com/metr/vivaria/blob/main/ui/src/run/RunPage.tsx) (Web UI), [`server/src/DriverImpl.ts`](https://github.com/metr/vivaria/blob/main/server/src/DriverImpl.ts) (Execution drivers), [`server/src/services/db/DBTraceEntries.ts`](https://github.com/metr/vivaria/blob/main/server/src/services/db/DBTraceEntries.ts) (Trace entries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_ui["Web UI<br/>[RunPage.tsx]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_server["Server API"]
  node_webserver["Web server<br/>[web_server.ts]"]
  node_routes["API routes<br/>[index.ts]"]
  node_hooks["Agent hooks API<br/>[hooks_routes.ts]"]
  node_rawroutes["Task routes<br/>[raw_routes.ts]"]
end

subgraph group_execution["Task and agent execution"]
  node_tasksetup["Task setup<br/>[tasks.ts]"]
  node_container["Container runner"]
  node_driver["Execution drivers<br/>[DriverImpl.ts]"]
  node_runqueue["Run queue<br/>[RunQueue.ts]"]
  node_labapi["LLM API proxy"]
  node_middleman["LLM forwarding<br/>[Middleman.ts]"]
end

subgraph group_research["Research and results"]
  node_intervention["Interventions"]
  node_db[("PostgreSQL<br/>[db.ts]")]
  node_trace["Trace entries<br/>[DBTraceEntries.ts]"]
  node_runui["Run review<br/>[RunPage.tsx]"]
  node_playground["Prompt playground<br/>[PlaygroundPage.tsx]"]
  node_inspect["Inspect importer<br/>[InspectImporter.ts]"]
  node_inspecthandler["Inspect event conversion"]
  node_runsui["Runs analysis<br/>[RunsPage.tsx]"]
end

node_researcher(("Researcher"))
node_auth(("Auth0"))

node_researcher -->|"uses"| node_ui
node_researcher -->|"uses"| node_cli
node_ui -.->|"authenticates with"| node_auth
node_ui -->|"requests"| node_webserver
node_cli -->|"calls API"| node_webserver
node_webserver -->|"dispatches"| node_routes
node_routes -->|"prepares tasks"| node_tasksetup
node_routes -->|"schedules runs"| node_runqueue
node_routes -->|"reads and writes"| node_db
node_tasksetup -->|"gets setup data"| node_driver
node_tasksetup -->|"builds task image"| node_container
node_container -->|"runs task"| node_driver
node_driver -->|"agent calls"| node_hooks
node_hooks -->|"records entries"| node_trace
node_trace -->|"persists entries"| node_db
node_driver -->|"requests generations"| node_labapi
node_labapi -->|"forwards requests"| node_middleman
node_labapi -->|"records API activity"| node_trace
node_ui -->|"renders run view"| node_runui
node_runui -->|"loads run data"| node_routes
node_runui -->|"submits annotations"| node_intervention
node_ui -->|"opens"| node_playground
node_playground -->|"uses API"| node_routes
node_ui -->|"opens"| node_runsui
node_runsui -->|"queries runs"| node_routes
node_inspect -->|"converts events"| node_inspecthandler
node_inspect -->|"imports entries"| node_trace

click node_ui "https://github.com/metr/vivaria/blob/main/ui/src/run/RunPage.tsx"
click node_cli "https://github.com/metr/vivaria/blob/main/cli/viv_cli/main.py"
click node_webserver "https://github.com/metr/vivaria/blob/main/server/src/web_server.ts"
click node_routes "https://github.com/metr/vivaria/blob/main/server/src/routes/index.ts"
click node_hooks "https://github.com/metr/vivaria/blob/main/server/src/routes/hooks_routes.ts"
click node_rawroutes "https://github.com/metr/vivaria/blob/main/server/src/routes/raw_routes.ts"
click node_intervention "https://github.com/metr/vivaria/blob/main/server/src/routes/intervention_routes.ts"
click node_db "https://github.com/metr/vivaria/blob/main/server/src/services/db/db.ts"
click node_trace "https://github.com/metr/vivaria/blob/main/server/src/services/db/DBTraceEntries.ts"
click node_tasksetup "https://github.com/metr/vivaria/blob/main/server/src/docker/tasks.ts"
click node_container "https://github.com/metr/vivaria/blob/main/server/src/docker/TaskContainerRunner.ts"
click node_driver "https://github.com/metr/vivaria/blob/main/server/src/DriverImpl.ts"
click node_runqueue "https://github.com/metr/vivaria/blob/main/server/src/RunQueue.ts"
click node_labapi "https://github.com/metr/vivaria/blob/main/server/src/services/PassthroughLabApiRequestHandler.ts"
click node_middleman "https://github.com/metr/vivaria/blob/main/server/src/services/Middleman.ts"
click node_runui "https://github.com/metr/vivaria/blob/main/ui/src/run/RunPage.tsx"
click node_playground "https://github.com/metr/vivaria/blob/main/ui/src/playground/PlaygroundPage.tsx"
click node_inspect "https://github.com/metr/vivaria/blob/main/server/src/inspect/InspectImporter.ts"
click node_inspecthandler "https://github.com/metr/vivaria/blob/main/server/src/inspect/InspectEventHandler.ts"
click node_runsui "https://github.com/metr/vivaria/blob/main/ui/src/runs/RunsPage.tsx"

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_ui,node_cli toneBlue
class node_webserver,node_routes,node_hooks,node_rawroutes toneAmber
class node_tasksetup,node_container,node_driver,node_runqueue,node_labapi,node_middleman toneMint
class node_intervention,node_db,node_trace,node_runui,node_playground,node_inspect,node_inspecthandler,node_runsui toneRose
class node_researcher,node_auth toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/metr/vivaria/blob/main/ui/src/run/RunPage.tsx): `ui/src/run/RunPage.tsx`
- [CLI](https://github.com/metr/vivaria/blob/main/cli/viv_cli/main.py): `cli/viv_cli/main.py`

### Server API

- [Web server](https://github.com/metr/vivaria/blob/main/server/src/web_server.ts): `server/src/web_server.ts`
- [API routes](https://github.com/metr/vivaria/blob/main/server/src/routes/index.ts): `server/src/routes/index.ts`
- [Agent hooks API](https://github.com/metr/vivaria/blob/main/server/src/routes/hooks_routes.ts): `server/src/routes/hooks_routes.ts`
- [Task routes](https://github.com/metr/vivaria/blob/main/server/src/routes/raw_routes.ts): `server/src/routes/raw_routes.ts`

### Task and agent execution

- [Task setup](https://github.com/metr/vivaria/blob/main/server/src/docker/tasks.ts): `server/src/docker/tasks.ts`
- [Container runner](https://github.com/metr/vivaria/blob/main/server/src/docker/TaskContainerRunner.ts): `server/src/docker/TaskContainerRunner.ts`
- [Execution drivers](https://github.com/metr/vivaria/blob/main/server/src/DriverImpl.ts): `server/src/DriverImpl.ts`
- [Run queue](https://github.com/metr/vivaria/blob/main/server/src/RunQueue.ts): `server/src/RunQueue.ts`
- [LLM API proxy](https://github.com/metr/vivaria/blob/main/server/src/services/PassthroughLabApiRequestHandler.ts): `server/src/services/PassthroughLabApiRequestHandler.ts`
- [LLM forwarding](https://github.com/metr/vivaria/blob/main/server/src/services/Middleman.ts): `server/src/services/Middleman.ts`

### Research and results

- [Interventions](https://github.com/metr/vivaria/blob/main/server/src/routes/intervention_routes.ts): `server/src/routes/intervention_routes.ts`
- [PostgreSQL](https://github.com/metr/vivaria/blob/main/server/src/services/db/db.ts): `server/src/services/db/db.ts`
- [Trace entries](https://github.com/metr/vivaria/blob/main/server/src/services/db/DBTraceEntries.ts): `server/src/services/db/DBTraceEntries.ts`
- [Run review](https://github.com/metr/vivaria/blob/main/ui/src/run/RunPage.tsx): `ui/src/run/RunPage.tsx`
- [Prompt playground](https://github.com/metr/vivaria/blob/main/ui/src/playground/PlaygroundPage.tsx): `ui/src/playground/PlaygroundPage.tsx`
- [Inspect importer](https://github.com/metr/vivaria/blob/main/server/src/inspect/InspectImporter.ts): `server/src/inspect/InspectImporter.ts`
- [Inspect event conversion](https://github.com/metr/vivaria/blob/main/server/src/inspect/InspectEventHandler.ts): `server/src/inspect/InspectEventHandler.ts`
- [Runs analysis](https://github.com/metr/vivaria/blob/main/ui/src/runs/RunsPage.tsx): `ui/src/runs/RunsPage.tsx`

### Other components

- **Researcher**
- **Auth0**

## Connections

- Researcher → Web UI: uses
- Researcher → CLI: uses
- Web UI → Auth0: authenticates with
- Web UI → Web server: requests
- CLI → Web server: calls API
- Web server → API routes: dispatches
- API routes → Task setup: prepares tasks
- API routes → Run queue: schedules runs
- API routes → PostgreSQL: reads and writes
- Task setup → Execution drivers: gets setup data
- Task setup → Container runner: builds task image
- Container runner → Execution drivers: runs task
- Execution drivers → Agent hooks API: agent calls
- Agent hooks API → Trace entries: records entries
- Trace entries → PostgreSQL: persists entries
- Execution drivers → LLM API proxy: requests generations
- LLM API proxy → LLM forwarding: forwards requests
- LLM API proxy → Trace entries: records API activity
- Web UI → Run review: renders run view
- Run review → API routes: loads run data
- Run review → Interventions: submits annotations
- Web UI → Prompt playground: opens
- Prompt playground → API routes: uses API
- Web UI → Runs analysis: opens
- Runs analysis → API routes: queries runs
- Inspect importer → Inspect event conversion: converts events
- Inspect importer → Trace entries: imports entries