# colemurray/background-agents architecture

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

- Interactive diagram: https://gitdiagram.com/colemurray/background-agents
- Repository: https://github.com/colemurray/background-agents

## Overview

Open-Inspect is a hosted background coding-agent system. A user or integration starts a coding session through the control plane, which authorizes and initializes a session, provisions a sandbox, and connects it to the agent runtime; session events, artifacts, and results return through control-plane APIs and storage. The README also documents multiplayer, scheduled and event-driven automations, parallel child sessions, and model-provider choices, represented here as capabilities without assuming unsampled call wiring. Source excerpts support the attachment-storage and sandbox-lifecycle links; other links follow the README architecture and module names, with implementation details not sampled.

Main entry points: [`packages/control-plane/src/session/server.ts`](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/server.ts) (Session runtime), [`packages/control-plane/src/routing/hono-app.ts`](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/routing/hono-app.ts) (HTTP routing), [`packages/control-plane/src/sandbox/lifecycle/manager.ts`](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/sandbox/lifecycle/manager.ts) (Sandbox lifecycle), [`packages/modal-infra/src/sandbox/manager.py`](https://github.com/colemurray/background-agents/blob/main/packages/modal-infra/src/sandbox/manager.py) (Agent environment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and identity"]
  node_routing["HTTP routing<br/>[hono-app.ts]"]
  node_auth["Identity and auth<br/>[authenticate.ts]"]
  node_authorization["Access control<br/>[service.ts]"]
end

subgraph group_sessions["Session orchestration"]
  node_session_api["Session APIs<br/>[sessions.ts]"]
  node_session_core["Session runtime<br/>[server.ts]"]
  node_session_ws["Realtime collaboration"]
  node_session_events["Events and messages<br/>[event-stream.ts]"]
  node_attachments["Attachments and media"]
end

subgraph group_execution["Sandbox execution"]
  node_sandbox_lifecycle["Sandbox lifecycle<br/>[manager.ts]"]
  node_sandbox_providers["Sandbox providers"]
  node_sandbox_runtime["Agent environment<br/>[manager.py]"]
  node_image_builds["Sandbox images<br/>[workflow.ts]"]
end

subgraph group_integrations["Automation and providers"]
  node_automations["Automations<br/>[automations.ts]"]
  node_scheduler["Scheduled work<br/>[scheduler.ts]"]
  node_provider_accounts["Model connections<br/>[service.ts]"]
  node_source_control["Source control<br/>[index.ts]"]
end

subgraph group_state["Persistence and hosting"]
  node_database[("Control-plane data<br/>[sql-database.ts]")]
  node_session_storage[("Session state<br/>[sql-storage.ts]")]
  node_object_storage[("Object storage<br/>[object-storage.ts]")]
  node_runtime_host["Runtime hosts<br/>[platform.ts]"]
end

node_clients(("Web and integrations"))
node_github(("GitHub"))
node_slack_linear(("Slack and Linear"))
node_model_providers(("AI model providers"))

node_clients -->|"send requests"| node_routing
node_routing -->|"authenticate"| node_auth
node_routing -->|"check access"| node_authorization
node_routing -->|"dispatch"| node_session_api
node_session_api -->|"manage sessions"| node_session_core
node_session_core -->|"read and write"| node_session_storage
node_runtime_host -->|"host"| node_session_core
node_session_core -->|"provision and resume"| node_sandbox_lifecycle
node_sandbox_lifecycle -->|"select provider"| node_sandbox_providers
node_sandbox_providers -->|"create environment"| node_sandbox_runtime
node_sandbox_lifecycle -->|"select image"| node_image_builds
node_sandbox_lifecycle -->|"persist lifecycle"| node_session_storage
node_sandbox_runtime -->|"send runtime events"| node_session_core
node_session_core -->|"record and stream"| node_session_events
node_session_core -->|"serve collaboration"| node_session_ws
node_session_core -->|"store attachments"| node_attachments
node_attachments -->|"put and delete"| node_object_storage
node_attachments -->|"register metadata"| node_session_core
node_session_api -->|"configure work"| node_automations
node_automations -->|"schedule runs"| node_scheduler
node_scheduler -->|"start sessions"| node_session_core
node_slack_linear -.->|"trigger work"| node_automations
node_github -.->|"send events"| node_automations
node_session_core -->|"resolve model access"| node_provider_accounts
node_provider_accounts -.->|"authorize accounts"| node_model_providers
node_sandbox_runtime -.->|"run agent"| node_model_providers
node_sandbox_runtime -->|"use repositories"| node_source_control
node_source_control -.->|"git and PR operations"| node_github
node_session_core -->|"persist control data"| node_database
node_session_core -->|"store media"| node_object_storage

click node_routing "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/routing/hono-app.ts"
click node_auth "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/auth/authenticate.ts"
click node_authorization "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/authorization/service.ts"
click node_session_api "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/routes/sessions.ts"
click node_session_core "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/server.ts"
click node_session_ws "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/websocket-manager.ts"
click node_session_events "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/event-stream.ts"
click node_attachments "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/services/session-attachment-storage.ts"
click node_sandbox_lifecycle "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/sandbox/lifecycle/manager.ts"
click node_sandbox_providers "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/sandbox/provider-factory.ts"
click node_sandbox_runtime "https://github.com/colemurray/background-agents/blob/main/packages/modal-infra/src/sandbox/manager.py"
click node_image_builds "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/image-builds/workflow.ts"
click node_automations "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/routes/automations.ts"
click node_scheduler "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/scheduler/scheduler.ts"
click node_provider_accounts "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/model-provider-accounts/service.ts"
click node_source_control "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/source-control/index.ts"
click node_database "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/db/sql-database.ts"
click node_session_storage "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/sql-storage.ts"
click node_object_storage "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/storage/object-storage.ts"
click node_runtime_host "https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/cloudflare/platform.ts"

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_routing,node_auth,node_authorization toneBlue
class node_session_api,node_session_core,node_session_ws,node_session_events,node_attachments toneAmber
class node_sandbox_lifecycle,node_sandbox_providers,node_sandbox_runtime,node_image_builds toneMint
class node_automations,node_scheduler,node_provider_accounts,node_source_control toneRose
class node_database,node_session_storage,node_object_storage,node_runtime_host,node_clients,node_github,node_slack_linear,node_model_providers toneIndigo
```

## Components

### Entry and identity

- [HTTP routing](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/routing/hono-app.ts): `packages/control-plane/src/routing/hono-app.ts`
- [Identity and auth](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/auth/authenticate.ts): `packages/control-plane/src/auth/authenticate.ts`
- [Access control](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/authorization/service.ts): `packages/control-plane/src/authorization/service.ts`

### Session orchestration

- [Session APIs](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/routes/sessions.ts): `packages/control-plane/src/routes/sessions.ts`
- [Session runtime](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/server.ts): `packages/control-plane/src/session/server.ts`
- [Realtime collaboration](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/websocket-manager.ts): `packages/control-plane/src/session/websocket-manager.ts`
- [Events and messages](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/event-stream.ts): `packages/control-plane/src/session/event-stream.ts`
- [Attachments and media](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/services/session-attachment-storage.ts): `packages/control-plane/src/session/services/session-attachment-storage.ts`

### Sandbox execution

- [Sandbox lifecycle](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/sandbox/lifecycle/manager.ts): `packages/control-plane/src/sandbox/lifecycle/manager.ts`
- [Sandbox providers](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/sandbox/provider-factory.ts): `packages/control-plane/src/sandbox/provider-factory.ts`
- [Agent environment](https://github.com/colemurray/background-agents/blob/main/packages/modal-infra/src/sandbox/manager.py): `packages/modal-infra/src/sandbox/manager.py`
- [Sandbox images](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/image-builds/workflow.ts): `packages/control-plane/src/image-builds/workflow.ts`

### Automation and providers

- [Automations](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/routes/automations.ts): `packages/control-plane/src/routes/automations.ts`
- [Scheduled work](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/scheduler/scheduler.ts): `packages/control-plane/src/scheduler/scheduler.ts`
- [Model connections](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/model-provider-accounts/service.ts): `packages/control-plane/src/model-provider-accounts/service.ts`
- [Source control](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/source-control/index.ts): `packages/control-plane/src/source-control/index.ts`

### Persistence and hosting

- [Control-plane data](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/db/sql-database.ts): `packages/control-plane/src/db/sql-database.ts`
- [Session state](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/session/sql-storage.ts): `packages/control-plane/src/session/sql-storage.ts`
- [Object storage](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/storage/object-storage.ts): `packages/control-plane/src/storage/object-storage.ts`
- [Runtime hosts](https://github.com/colemurray/background-agents/blob/main/packages/control-plane/src/cloudflare/platform.ts): `packages/control-plane/src/cloudflare/platform.ts`

### Other components

- **Web and integrations**
- **GitHub**
- **Slack and Linear**
- **AI model providers**

## Connections

- Web and integrations → HTTP routing: send requests
- HTTP routing → Identity and auth: authenticate
- HTTP routing → Access control: check access
- HTTP routing → Session APIs: dispatch
- Session APIs → Session runtime: manage sessions
- Session runtime → Session state: read and write
- Runtime hosts → Session runtime: host
- Session runtime → Sandbox lifecycle: provision and resume
- Sandbox lifecycle → Sandbox providers: select provider
- Sandbox providers → Agent environment: create environment
- Sandbox lifecycle → Sandbox images: select image
- Sandbox lifecycle → Session state: persist lifecycle
- Agent environment → Session runtime: send runtime events
- Session runtime → Events and messages: record and stream
- Session runtime → Realtime collaboration: serve collaboration
- Session runtime → Attachments and media: store attachments
- Attachments and media → Object storage: put and delete
- Attachments and media → Session runtime: register metadata
- Session APIs → Automations: configure work
- Automations → Scheduled work: schedule runs
- Scheduled work → Session runtime: start sessions
- Slack and Linear → Automations: trigger work
- GitHub → Automations: send events
- Session runtime → Model connections: resolve model access
- Model connections → AI model providers: authorize accounts
- Agent environment → AI model providers: run agent
- Agent environment → Source control: use repositories
- Source control → GitHub: git and PR operations
- Session runtime → Control-plane data: persist control data
- Session runtime → Object storage: store media