# paradigmxyz/centaur architecture

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

- Interactive diagram: https://gitdiagram.com/paradigmxyz/centaur
- Repository: https://github.com/paradigmxyz/centaur

## Overview

Centaur is a self-hosted shared-agent platform: users start conversations through Slack or the API, the control plane manages durable sessions and assigns isolated sandboxes, and harnesses execute work with approved tools. Results and progress return through the initiating channel. The repository also includes durable workflows, credential-protected outbound access, team-facing configuration, and integrations such as GitHub. Relationships below follow explicit README descriptions or sampled imports/calls; unsampled subsystem details are represented at their enclosing directory where appropriate.

Main entry points: [`services/api-rs/crates/centaur-api-server/src/routes.rs`](https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-api-server/src/routes.rs) (Centaur API), [`crates/harness-server/src/server.rs`](https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/server.rs) (Harness server), [`services/sandbox`](https://github.com/paradigmxyz/centaur/tree/main/services/sandbox) (Sandbox environment), [`services/slackbotv2/src/index.ts`](https://github.com/paradigmxyz/centaur/blob/main/services/slackbotv2/src/index.ts) (Slack bot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Ingress and delivery"]
  node_slack["Slack bot<br/>[index.ts]"]
  node_github["GitHub bot<br/>[issue-manager.ts]"]
end

subgraph group_control["Control plane"]
  node_api["Centaur API<br/>[routes.rs]"]
  node_session["Session runtime<br/>[lib.rs]"]
  node_sandboxmgr["Sandbox manager<br/>[manager.rs]"]
  node_console["Team console"]
end

subgraph group_execution["Agent execution"]
  node_sandbox["Sandbox environment"]
  node_harness["Harness server<br/>[server.rs]"]
  node_claude["Claude harness<br/>[claude.rs]"]
  node_codex["Codex harness<br/>[codex.rs]"]
  node_turn["Turn protocol<br/>[turn.rs]"]
  node_harnessotel["Harness telemetry<br/>[otel.rs]"]
end

subgraph group_automation["Tools and workflows"]
  node_toolshim["Sandbox tool shims"]
  node_toolplugins["Shared tool plugins"]
  node_sdk["Tool SDK<br/>[tool_sdk.py]"]
  node_workflow["Workflow runtime<br/>[workflow_engine.py]"]
  node_companyctx["Company context<br/>[tasks.rs]"]
  node_embedworkflow["Context embeddings"]
end

subgraph group_security["State and security"]
  node_store[("Durable state<br/>[lib.rs]")]
  node_proxy["Credential proxy<br/>[lib.rs]"]
end

node_actor(("Slack or API user"))
node_slacksvc["Slack"]
node_kubernetes["Kubernetes"]
node_postgres[("Postgres")]
node_external["Approved services"]

node_actor -->|"starts conversation"| node_slack
node_actor -->|"calls API"| node_api
node_slack -->|"requests sessions"| node_api
node_api -->|"manages sessions"| node_session
node_api -->|"assigns sandbox"| node_sandboxmgr
node_api -->|"routes workflow work"| node_workflow
node_session -->|"persists transcript"| node_store
node_sandboxmgr -->|"provisions sandbox"| node_kubernetes
node_sandbox -->|"runs harness"| node_harness
node_harness -->|"dispatches"| node_claude
node_harness -->|"dispatches"| node_codex
node_harness -->|"handles turns"| node_turn
node_harness -->|"records telemetry"| node_harnessotel
node_sandbox -->|"uses shims"| node_toolshim
node_toolshim -->|"invokes tools"| node_toolplugins
node_toolplugins -->|"uses SDK"| node_sdk
node_workflow -->|"calls tools"| node_toolplugins
node_companyctx -.->|"uses storage"| node_postgres
node_embedworkflow -->|"runs in host"| node_workflow
node_sandbox -->|"routes outbound traffic"| node_proxy
node_proxy -->|"injects credentials"| node_external
node_api -->|"returns progress"| node_slack
node_console -.->|"configures platform"| node_api
node_github -.->|"starts agent sessions"| node_api

click node_slack "https://github.com/paradigmxyz/centaur/blob/main/services/slackbotv2/src/index.ts"
click node_github "https://github.com/paradigmxyz/centaur/blob/main/services/githubbot/src/issue-manager.ts"
click node_api "https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-api-server/src/routes.rs"
click node_session "https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-session-runtime/src/lib.rs"
click node_sandboxmgr "https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-sandbox-manager/src/manager.rs"
click node_sandbox "https://github.com/paradigmxyz/centaur/tree/main/services/sandbox"
click node_harness "https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/server.rs"
click node_claude "https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/claude.rs"
click node_codex "https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/codex.rs"
click node_turn "https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/turn.rs"
click node_harnessotel "https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/otel.rs"
click node_toolshim "https://github.com/paradigmxyz/centaur/blob/main/services/sandbox/install_tool_shims.py"
click node_toolplugins "https://github.com/paradigmxyz/centaur/tree/main/tools"
click node_sdk "https://github.com/paradigmxyz/centaur/blob/main/centaur_sdk/tool_sdk.py"
click node_workflow "https://github.com/paradigmxyz/centaur/blob/main/services/workflow-python/api/workflow_engine.py"
click node_companyctx "https://github.com/paradigmxyz/centaur/blob/main/services/company-context/src/tasks.rs"
click node_embedworkflow "https://github.com/paradigmxyz/centaur/blob/main/workflows/company_context_embeddings.py"
click node_store "https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-session-sqlx/src/lib.rs"
click node_proxy "https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-iron-proxy/src/lib.rs"
click node_console "https://github.com/paradigmxyz/centaur/blob/main/services/console/app/controllers/console_controller.rb"

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_slack,node_github,node_actor toneBlue
class node_api,node_session,node_sandboxmgr,node_console,node_postgres toneAmber
class node_sandbox,node_harness,node_claude,node_codex,node_turn,node_harnessotel toneMint
class node_toolshim,node_toolplugins,node_sdk,node_workflow,node_companyctx,node_embedworkflow toneRose
class node_store,node_proxy,node_slacksvc,node_kubernetes,node_external toneIndigo
```

## Components

### Ingress and delivery

- [Slack bot](https://github.com/paradigmxyz/centaur/blob/main/services/slackbotv2/src/index.ts): `services/slackbotv2/src/index.ts`
- [GitHub bot](https://github.com/paradigmxyz/centaur/blob/main/services/githubbot/src/issue-manager.ts): `services/githubbot/src/issue-manager.ts`

### Control plane

- [Centaur API](https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-api-server/src/routes.rs): `services/api-rs/crates/centaur-api-server/src/routes.rs`
- [Session runtime](https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-session-runtime/src/lib.rs): `services/api-rs/crates/centaur-session-runtime/src/lib.rs`
- [Sandbox manager](https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-sandbox-manager/src/manager.rs): `services/api-rs/crates/centaur-sandbox-manager/src/manager.rs`
- [Team console](https://github.com/paradigmxyz/centaur/blob/main/services/console/app/controllers/console_controller.rb): `services/console/app/controllers/console_controller.rb`

### Agent execution

- [Sandbox environment](https://github.com/paradigmxyz/centaur/tree/main/services/sandbox): `services/sandbox`
- [Harness server](https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/server.rs): `crates/harness-server/src/server.rs`
- [Claude harness](https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/claude.rs): `crates/harness-server/src/claude.rs`
- [Codex harness](https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/codex.rs): `crates/harness-server/src/codex.rs`
- [Turn protocol](https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/turn.rs): `crates/harness-server/src/turn.rs`
- [Harness telemetry](https://github.com/paradigmxyz/centaur/blob/main/crates/harness-server/src/otel.rs): `crates/harness-server/src/otel.rs`

### Tools and workflows

- [Sandbox tool shims](https://github.com/paradigmxyz/centaur/blob/main/services/sandbox/install_tool_shims.py): `services/sandbox/install_tool_shims.py`
- [Shared tool plugins](https://github.com/paradigmxyz/centaur/tree/main/tools): `tools`
- [Tool SDK](https://github.com/paradigmxyz/centaur/blob/main/centaur_sdk/tool_sdk.py): `centaur_sdk/tool_sdk.py`
- [Workflow runtime](https://github.com/paradigmxyz/centaur/blob/main/services/workflow-python/api/workflow_engine.py): `services/workflow-python/api/workflow_engine.py`
- [Company context](https://github.com/paradigmxyz/centaur/blob/main/services/company-context/src/tasks.rs): `services/company-context/src/tasks.rs`
- [Context embeddings](https://github.com/paradigmxyz/centaur/blob/main/workflows/company_context_embeddings.py): `workflows/company_context_embeddings.py`

### State and security

- [Durable state](https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-session-sqlx/src/lib.rs): `services/api-rs/crates/centaur-session-sqlx/src/lib.rs`
- [Credential proxy](https://github.com/paradigmxyz/centaur/blob/main/services/api-rs/crates/centaur-iron-proxy/src/lib.rs): `services/api-rs/crates/centaur-iron-proxy/src/lib.rs`

### Other components

- **Slack or API user**
- **Slack**
- **Kubernetes**
- **Postgres**
- **Approved services**

## Connections

- Slack or API user → Slack bot: starts conversation (evidence: `README.md`)
- Slack or API user → Centaur API: calls API (evidence: `README.md`)
- Slack bot → Centaur API: requests sessions (evidence: `README.md`)
- Centaur API → Session runtime: manages sessions (evidence: `README.md`)
- Centaur API → Sandbox manager: assigns sandbox (evidence: `README.md`)
- Centaur API → Workflow runtime: routes workflow work (evidence: `README.md`)
- Session runtime → Durable state: persists transcript (evidence: `README.md`)
- Sandbox manager → Kubernetes: provisions sandbox (evidence: `README.md`)
- Sandbox environment → Harness server: runs harness (evidence: `README.md`)
- Harness server → Claude harness: dispatches (evidence: `crates/harness-server/src/server.rs`)
- Harness server → Codex harness: dispatches (evidence: `crates/harness-server/src/server.rs`)
- Harness server → Turn protocol: handles turns (evidence: `crates/harness-server/src/server.rs`)
- Harness server → Harness telemetry: records telemetry (evidence: `crates/harness-server/src/server.rs`)
- Sandbox environment → Sandbox tool shims: uses shims (evidence: `README.md`)
- Sandbox tool shims → Shared tool plugins: invokes tools (evidence: `README.md`)
- Shared tool plugins → Tool SDK: uses SDK (evidence: `tools/business/attio/client.py`)
- Workflow runtime → Shared tool plugins: calls tools (evidence: `README.md`)
- Company context → Postgres: uses storage
- Context embeddings → Workflow runtime: runs in host (evidence: `workflows/company_context_embeddings.py`)
- Sandbox environment → Credential proxy: routes outbound traffic (evidence: `README.md`)
- Credential proxy → Approved services: injects credentials (evidence: `README.md`)
- Centaur API → Slack bot: returns progress (evidence: `README.md`)
- Team console → Centaur API: configures platform
- GitHub bot → Centaur API: starts agent sessions
