How paradigmxyz/centaur works
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: routes.rs Centaur API · server.rs Harness server · sandbox Sandbox environment · index.ts Slack bot
Components 25
Ingress and delivery
- Slack bot
services/slackbotv2/src/index.ts - GitHub bot
services/githubbot/src/issue-manager.ts
Control plane
- Centaur API
services/api-rs/crates/centaur-api-server/src/routes.rs - Session runtime
services/api-rs/crates/centaur-session-runtime/src/lib.rs - Sandbox manager
services/api-rs/crates/centaur-sandbox-manager/src/manager.rs - Team console
services/console/app/controllers/console_controller.rb
Agent execution
- Sandbox environment
services/sandbox - Harness server
crates/harness-server/src/server.rs - Claude harness
crates/harness-server/src/claude.rs - Codex harness
crates/harness-server/src/codex.rs - Turn protocol
crates/harness-server/src/turn.rs - Harness telemetry
crates/harness-server/src/otel.rs
Tools and workflows
- Sandbox tool shims
services/sandbox/install_tool_shims.py - Shared tool plugins
tools - Tool SDK
centaur_sdk/tool_sdk.py - Workflow runtime
services/workflow-python/api/workflow_engine.py - Company context
services/company-context/src/tasks.rs - Context embeddings
workflows/company_context_embeddings.py
State and security
- Durable state
services/api-rs/crates/centaur-session-sqlx/src/lib.rs - Credential proxy
services/api-rs/crates/centaur-iron-proxy/src/lib.rs
Other components
- Slack or API user
- Slack
- Kubernetes
- Postgres
- Approved services
Connections 24
- Slack or API user → Slack bot: starts conversation
README.md - Slack or API user → Centaur API: calls API
README.md - Slack bot → Centaur API: requests sessions
README.md - Centaur API → Session runtime: manages sessions
README.md - Centaur API → Sandbox manager: assigns sandbox
README.md - Centaur API → Workflow runtime: routes workflow work
README.md - Session runtime → Durable state: persists transcript
README.md - Sandbox manager → Kubernetes: provisions sandbox
README.md - Sandbox environment → Harness server: runs harness
README.md - Harness server → Claude harness: dispatches
crates/harness-server/src/server.rs - Harness server → Codex harness: dispatches
crates/harness-server/src/server.rs - Harness server → Turn protocol: handles turns
crates/harness-server/src/server.rs - Harness server → Harness telemetry: records telemetry
crates/harness-server/src/server.rs - Sandbox environment → Sandbox tool shims: uses shims
README.md - Sandbox tool shims → Shared tool plugins: invokes tools
README.md - Shared tool plugins → Tool SDK: uses SDK
tools/business/attio/client.py - Workflow runtime → Shared tool plugins: calls tools
README.md - Company context → Postgres: uses storage
- Context embeddings → Workflow runtime: runs in host
workflows/company_context_embeddings.py - Sandbox environment → Credential proxy: routes outbound traffic
README.md - Credential proxy → Approved services: injects credentials
README.md - Centaur API → Slack bot: returns progress
README.md - Team console → Centaur API: configures platform
- GitHub bot → Centaur API: starts agent sessions