# parcha-ai/agentrun architecture

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

- Interactive diagram: https://gitdiagram.com/parcha-ai/agentrun
- Repository: https://github.com/parcha-ai/agentrun

## Overview

AgentRun is a platform for running agents with durable execution, computer access, learning, and a control plane. Users configure an agent or workflow in the console or through an API, start a run, and inspect its results and state. The server validates and launches work through a harness and runner; runs use configured models and optional computer environments, while the store supports persistence and recovery. Learning, workflow authoring, approvals, and operational analytics are distinct product capabilities. The graph follows documented capabilities and sampled imports/calls; several feature implementations are unsampled, so their links are documented or left unverified.

Main entry points: [`packages/serve/src/server.ts`](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/server.ts) (AgentRun server), [`packages/serve/src/run-launch.ts`](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/run-launch.ts) (Run launch), [`packages/serve/src/learning-routes.ts`](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/learning-routes.ts) (Learning API), [`packages/serve/src/harness-table.ts`](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/harness-table.ts) (Harness registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_console["Console<br/>[App.tsx]"]
  node_console_api["Console API client<br/>[client.ts]"]
end

subgraph group_execution["Run execution"]
  node_server["AgentRun server<br/>[server.ts]"]
  node_validation["Agent validation<br/>[validate.ts]"]
  node_launch["Run launch<br/>[run-launch.ts]"]
  node_harnesses["Harness registry<br/>[harness-table.ts]"]
  node_model["Model routing<br/>[model.ts]"]
  node_runner["Runner dispatch<br/>[main.ts]"]
  node_store[("Durable run store<br/>[storage.ts]")]
end

subgraph group_learning["Learning and workflows"]
  node_learning_routes["Learning API<br/>[learning-routes.ts]"]
  node_learning["Learning engine<br/>[learning.ts]"]
  node_learning_skills["Learned skills<br/>[skills.ts]"]
  node_workflow["Workflow authoring"]
end

subgraph group_computer["Computer environments"]
  node_computer_sdk["Computer SDK<br/>[protocol.ts]"]
  node_ui_engine["Computer UI engine<br/>[ui-engine.ts]"]
  node_computer_daemon["Computer daemon<br/>[main.go]"]
  node_mac_ui["macOS UI driver<br/>[Engine.swift]"]
  node_browser_live["Browser live view<br/>[server.ts]"]
end

subgraph group_interfaces["Clients and integrations"]
  node_ts_client["TypeScript SDK<br/>[client.ts]"]
  node_py_client["Python SDK<br/>[_client.py]"]
  node_cli["AgentRun CLI<br/>[cli.mjs]"]
end

node_user(("Agent operator"))
node_model_provider{{"Model provider"}}
node_harness{{"Agent harness"}}
node_computer{{"Computer environment"}}

node_user -->|"configures and starts"| node_console
node_console -->|"uses API"| node_console_api
node_console_api -->|"sends requests"| node_server
node_user -->|"starts runs"| node_ts_client
node_user -->|"starts runs"| node_py_client
node_user -->|"starts platform"| node_cli
node_ts_client -.->|"sends requests"| node_server
node_py_client -.->|"sends requests"| node_server
node_cli -.->|"starts server"| node_server
node_server -.->|"validates inputs"| node_validation
node_server -.->|"launches runs"| node_launch
node_server -.->|"routes learning"| node_learning_routes
node_server -.->|"persists state"| node_store
node_launch -.->|"selects harness"| node_harnesses
node_launch -.->|"resolves model"| node_model
node_runner -->|"opens store"| node_store
node_runner -->|"resolves run loop"| node_harnesses
node_harnesses -.->|"dispatches work"| node_harness
node_model -.->|"routes inference"| node_model_provider
node_learning_routes -->|"uses learning logic"| node_learning
node_learning_routes -->|"checks skills"| node_learning_skills
node_learning -.->|"stores learning"| node_store
node_workflow -.->|"defines workflows"| node_server
node_computer_sdk -->|"defines UI protocol"| node_ui_engine
node_ui_engine -.->|"drives interactions"| node_computer
node_computer_daemon -->|"serves computer protocol"| node_computer
node_mac_ui -.->|"drives macOS UI"| node_computer
node_browser_live -.->|"streams live view"| node_computer

click node_console "https://github.com/parcha-ai/agentrun/blob/main/apps/console/src/App.tsx"
click node_console_api "https://github.com/parcha-ai/agentrun/blob/main/apps/console/src/lib/client.ts"
click node_server "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/server.ts"
click node_validation "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/validate.ts"
click node_launch "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/run-launch.ts"
click node_harnesses "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/harness-table.ts"
click node_model "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/model.ts"
click node_runner "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/runner/main.ts"
click node_store "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/store/journal/storage.ts"
click node_learning_routes "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/learning-routes.ts"
click node_learning "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/learning.ts"
click node_learning_skills "https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/learn/skills.ts"
click node_workflow "https://github.com/parcha-ai/agentrun/blob/main/packages/dsl/src/author-references.ts"
click node_computer_sdk "https://github.com/parcha-ai/agentrun/blob/main/packages/computer/src/protocol.ts"
click node_ui_engine "https://github.com/parcha-ai/agentrun/blob/main/packages/computer/src/ui-engine.ts"
click node_computer_daemon "https://github.com/parcha-ai/agentrun/blob/main/packages/computer/daemon/cmd/computerd/main.go"
click node_mac_ui "https://github.com/parcha-ai/agentrun/blob/main/packages/computer/daemon-macos/Sources/ComputerdKit/UI/Engine.swift"
click node_browser_live "https://github.com/parcha-ai/agentrun/blob/main/packages/pi-browser/src/live-view/server.ts"
click node_ts_client "https://github.com/parcha-ai/agentrun/blob/main/packages/client/src/client.ts"
click node_py_client "https://github.com/parcha-ai/agentrun/blob/main/python/agentrun/_client.py"
click node_cli "https://github.com/parcha-ai/agentrun/blob/main/packages/agentrun/lib/cli.mjs"

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_console,node_console_api toneBlue
class node_server,node_validation,node_launch,node_harnesses,node_model,node_runner,node_store toneAmber
class node_learning_routes,node_learning,node_learning_skills,node_workflow toneMint
class node_computer_sdk,node_ui_engine,node_computer_daemon,node_mac_ui,node_browser_live toneRose
class node_ts_client,node_py_client,node_cli,node_user,node_model_provider,node_harness,node_computer toneIndigo
```

## Components

### Control plane

- [Console](https://github.com/parcha-ai/agentrun/blob/main/apps/console/src/App.tsx): `apps/console/src/App.tsx`
- [Console API client](https://github.com/parcha-ai/agentrun/blob/main/apps/console/src/lib/client.ts): `apps/console/src/lib/client.ts`

### Run execution

- [AgentRun server](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/server.ts): `packages/serve/src/server.ts`
- [Agent validation](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/validate.ts): `packages/serve/src/validate.ts`
- [Run launch](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/run-launch.ts): `packages/serve/src/run-launch.ts`
- [Harness registry](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/harness-table.ts): `packages/serve/src/harness-table.ts`
- [Model routing](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/model.ts): `packages/serve/src/model.ts`
- [Runner dispatch](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/runner/main.ts): `packages/serve/src/runner/main.ts`
- [Durable run store](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/store/journal/storage.ts): `packages/serve/src/store/journal/storage.ts`

### Learning and workflows

- [Learning API](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/learning-routes.ts): `packages/serve/src/learning-routes.ts`
- [Learning engine](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/learning.ts): `packages/serve/src/learning.ts`
- [Learned skills](https://github.com/parcha-ai/agentrun/blob/main/packages/serve/src/learn/skills.ts): `packages/serve/src/learn/skills.ts`
- [Workflow authoring](https://github.com/parcha-ai/agentrun/blob/main/packages/dsl/src/author-references.ts): `packages/dsl/src/author-references.ts`

### Computer environments

- [Computer SDK](https://github.com/parcha-ai/agentrun/blob/main/packages/computer/src/protocol.ts): `packages/computer/src/protocol.ts`
- [Computer UI engine](https://github.com/parcha-ai/agentrun/blob/main/packages/computer/src/ui-engine.ts): `packages/computer/src/ui-engine.ts`
- [Computer daemon](https://github.com/parcha-ai/agentrun/blob/main/packages/computer/daemon/cmd/computerd/main.go): `packages/computer/daemon/cmd/computerd/main.go`
- [macOS UI driver](https://github.com/parcha-ai/agentrun/blob/main/packages/computer/daemon-macos/Sources/ComputerdKit/UI/Engine.swift): `packages/computer/daemon-macos/Sources/ComputerdKit/UI/Engine.swift`
- [Browser live view](https://github.com/parcha-ai/agentrun/blob/main/packages/pi-browser/src/live-view/server.ts): `packages/pi-browser/src/live-view/server.ts`

### Clients and integrations

- [TypeScript SDK](https://github.com/parcha-ai/agentrun/blob/main/packages/client/src/client.ts): `packages/client/src/client.ts`
- [Python SDK](https://github.com/parcha-ai/agentrun/blob/main/python/agentrun/_client.py): `python/agentrun/_client.py`
- [AgentRun CLI](https://github.com/parcha-ai/agentrun/blob/main/packages/agentrun/lib/cli.mjs): `packages/agentrun/lib/cli.mjs`

### Other components

- **Agent operator**
- **Model provider**
- **Agent harness**
- **Computer environment**

## Connections

- Agent operator → Console: configures and starts
- Console → Console API client: uses API (evidence: `apps/console/src/App.tsx`)
- Console API client → AgentRun server: sends requests (evidence: `apps/console/src/lib/client.ts`)
- Agent operator → TypeScript SDK: starts runs
- Agent operator → Python SDK: starts runs
- Agent operator → AgentRun CLI: starts platform
- TypeScript SDK → AgentRun server: sends requests
- Python SDK → AgentRun server: sends requests
- AgentRun CLI → AgentRun server: starts server
- AgentRun server → Agent validation: validates inputs
- AgentRun server → Run launch: launches runs
- AgentRun server → Learning API: routes learning (evidence: `packages/serve/src/server.ts`)
- AgentRun server → Durable run store: persists state
- Run launch → Harness registry: selects harness
- Run launch → Model routing: resolves model
- Runner dispatch → Durable run store: opens store (evidence: `packages/serve/src/runner/main.ts`)
- Runner dispatch → Harness registry: resolves run loop (evidence: `packages/serve/src/runner/main.ts`)
- Harness registry → Agent harness: dispatches work
- Model routing → Model provider: routes inference
- Learning API → Learning engine: uses learning logic (evidence: `packages/serve/src/learning-routes.ts`)
- Learning API → Learned skills: checks skills (evidence: `packages/serve/src/learning-routes.ts`)
- Learning engine → Durable run store: stores learning
- Workflow authoring → AgentRun server: defines workflows
- Computer SDK → Computer UI engine: defines UI protocol (evidence: `packages/computer/src/ui-engine.ts`)
- Computer UI engine → Computer environment: drives interactions
- Computer daemon → Computer environment: serves computer protocol (evidence: `packages/computer/daemon/cmd/computerd/main.go`)
- macOS UI driver → Computer environment: drives macOS UI
- Browser live view → Computer environment: streams live view