Centaur

Features

• Slack-native agent conversations: mention the bot in Slack and get progress plus final answers back in the thread.
• Real execution environment: each conversation runs in an isolated Kubernetes sandbox with a shell, workspace, git, Python, Node.js, Bun, and common development tools. For local setup, a lightweight k3s-based cluster is enough; you do not need a full production Kubernetes installation.
• Bring your own harness: run CLI-based agents such as Amp, Claude Code, Codex, or deployment-specific harnesses.
• Shared tools: add Python tool plugins once and make them available to every agent conversation.
• Durable workflows: run jobs that can sleep, resume, wait for events, start child agents, and survive service restarts.
• Credential boundaries: agents can use approved services without receiving raw API keys in their environment.
• Replayable state: messages, executions, events, and delivery state are stored so clients can reconnect without losing the result.
• Organization overlays: layer in your own tools, workflows, personas, skills, and prompts without forking the base platform.

...and a lot more.

Overview

Centaur is a self-hosted agent platform for teams that want one shared agent instead of many one-off local setups.

# 1. Ask from Slack.
@centaur can you figure out why the billing tests are failing?

# 2. Centaur assigns a sandbox for the thread.
# The agent can inspect code, run commands, and call approved tools.

# 3. Progress and the final answer are delivered back to Slack.

You can also drive Centaur directly through the API:

POST /api/session/{thread_key}          # create or reuse a session
POST /api/session/{thread_key}/messages # store the user turn
POST /api/session/{thread_key}/execute  # start the agent
GET  /api/session/{thread_key}/events   # stream or replay output

The platform handles sandbox lifecycle, durable transcript storage, tool access, credential injection, workflow execution, and final delivery.

What Centaur Is Good For

• investigating CI failures
• answering questions with internal tools
• summarizing Slack threads or customer context
• running recurring checks and digests
• coordinating multi-step operational workflows
• giving agents access to a real repo and test environment
• standardizing agent behavior across a team

How It Works

Slack or API
    |
    v
Centaur API
    |
    +-- Postgres durable state
    +-- tool metadata and workflow runtime
    +-- sandbox assignment
    |
    v
Kubernetes sandbox
    |
    +-- agent harness
    +-- workspace and shell
    +-- local tool CLI shims
    |
    v
Controlled outbound access

The main directories are:

• services/api-rs — Rust control plane for agents, tools, workflows, auth, and durable state
• services/slackbotv2 — Slack event handling and Slack delivery
• services/sandbox — agent container image and harness adapter
• iron-proxy (service) — controlled outbound access and credential injection
• tools — tool plugins
• workflows — workflow plugins

Getting Started

Centaur runs locally on Kubernetes, but local setup does not require a full production Kubernetes installation. A lightweight k3s cluster on a small always-on host is enough. The expected local checkout path is:

/Users/magelinskaas/paradigmxyz/centaur

Clone the repo and enter it:

git clone <repo-url>
cd centaur

Install the local command runner:

brew install just

For a first-time local boot, Centaur needs these infrastructure secrets in your shell:

export OP_SERVICE_ACCOUNT_TOKEN=...
export OP_VAULT=...
export SLACK_BOT_TOKEN=...
export SLACK_SIGNING_SECRET=...
export SLACKBOT_API_KEY=...

To boot optional Teams ingress locally, also export:

export TEAMS_BOT_APP_ID=...
export TEAMS_BOT_APP_PASSWORD=...
export TEAMS_BOT_APP_TENANT_ID=...
# TEAMSBOT_API_KEY is generated by bootstrap when omitted.

Create the Slackbot app at api.slack.com/apps. Use the app's Bot User OAuth Token for SLACK_BOT_TOKEN and its Signing Secret for SLACK_SIGNING_SECRET.

What they are for:

• OP_SERVICE_ACCOUNT_TOKEN: lets iron-proxy resolve 1Password-backed runtime secrets
• OP_VAULT: the 1Password vault name or id to read from
• SLACK_BOT_TOKEN: Slack bot token for the local Slackbot service
• SLACK_SIGNING_SECRET: verifies incoming Slack requests
• SLACKBOT_API_KEY: API key the Slackbot uses to call Centaur
• CENTAUR_APIRS_ADMIN_API_KEY: optional static bearer token with full access to api-rs
• CENTAUR_JWT_SIGNING_SECRET: signs short-lived Console and sandbox JWTs accepted by api-rs
• TEAMS_BOT_APP_ID, TEAMS_BOT_APP_PASSWORD, TEAMS_BOT_APP_TENANT_ID: optional Teams ingress app credentials when teamsbot.enabled=true
• TEAMSBOT_API_KEY: API key the Teamsbot uses to call Centaur; generated by local bootstrap when Teams credentials are present and this is omitted

Then create local Kubernetes Secrets from those environment variables and boot the stack:

just bootstrap-secrets
just up

After just up finishes, use Slack or the API examples in the Developer Guide.

For a more explicit path, see Running Centaur on a Mac Mini-style setup. It covers k3s on a small VPS, DigitalOcean droplet, Linux box, or Mac Mini-style host.

Tools

Tools are small Python plugins. A tool can wrap an internal service, public API, database, search endpoint, deployment system, or anything else an agent should be allowed to use.

tools/my_tool/
├── __init__.py
├── client.py
├── cli.py
├── .env.example
└── pyproject.toml

Each runtime tool should declare a [project.scripts] entry so sandbox startup can install it as a local CLI shim. Agents discover installed tools with:

centaur-tools list
my-tool --help

Workflow handlers can still invoke tools through ctx.call_tool(...); the workflow host uses the generated centaur-tools bridge for that compatibility path. api-rs does not expose legacy HTTP tool-method routes as the current sandbox tool registry.

Workflows

Workflows are Python functions with durable steps.

WORKFLOW_NAME = "daily_digest"

async def handler(inp, ctx):
    data = await ctx.step("collect", lambda: collect_digest_data(inp))
    summary = await ctx.run_agent("summarize", text=f"Summarize this: {data}")
    return {"summary": summary}

Use workflows when a task should run longer than one request, wait for something external, run on a schedule, or coordinate multiple agent turns.

Security Model

Centaur is designed around practical isolation and auditability:

• each conversation runs in a Kubernetes sandbox with a default-deny NetworkPolicy
• sandboxes call approved local tool CLI shims and reach the outside world only through a per-sandbox iron-proxy
• sandboxes only ever see placeholder strings for upstream credentials; real values are swapped in by iron-proxy only on outbound requests to the specific hosts and headers a secret is bound to
• messages, executions, events, and delivery state are persisted
• outbound activity can be audited

See Security for the full threat model and the mechanisms behind each of these points, including known limitations like the shared credential vault.

Documentation

• Docs app — Vocs documentation source
• Quickstart — boot the local Kubernetes stack and run one agent turn
• Deploying in Production — production secrets, Slack, Helm, and verification
• Architecture — control plane, sandbox runtime, tools, workflows, and credential injection
• Developer Guide — full local setup, architecture, API contracts, migrations, testing, and conventions
• Tools — built-in tool plugins
• Workflows — external workflow plugins
• Agent plugin — connect Codex, Claude Code, and other MCP clients to Centaur
• API service — Rust control plane
• Slackbot — Slack integration
• Sandbox — agent runtime image

Contributing

Before pushing changes, build and test the affected service locally:

just build-one <service>
just deploy

For Python checks:

uv run ruff check .
uv run ruff format .
uv run pytest

See the Developer Guide for code conventions and end-to-end testing instructions.

Acknowledgements

Centaur builds on excellent open-source infrastructure, including Rust, Axum, Kubernetes, iron-proxy, and the agent harnesses teams choose to run inside the sandbox.