centaur
Official Centaur plugins for agent clients.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/paradigmxyz/centaur with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/paradigmxyz/centaur'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/paradigmxyz--centaur)HTML
<a href="/listings/paradigmxyz--centaur"><img src="/api/listings/paradigmxyz--centaur/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](https://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](https://docs.iron.sh) 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](AGENTS.md#e2e-testing-without-slack).
For a more explicit path, see [Running Centaur on a Mac Mini-style setup](docs/pages/mac-mini-setup.mdx). It covers k3s on a small VPS, DigitalOcean droplet, Linux box, or Mac Mini-style host.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 27 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "centaur",
- "owner": {
- "name": "Paradigm",
- "url": "https://github.com/paradigmxyz"
- },
- "description": "Official Centaur plugins for agent clients.",
- "version": "0.1.0",
- "plugins": [
- {
- "name": "centaur",
- "displayName": "Centaur",
- "source": "./plugins/centaur",
- "description": "Use your team's approved Centaur tools through MCP.",
- "version": "0.1.0",
- "author": {
- "name": "Paradigm",
- "url": "https://github.com/paradigmxyz"
- },
- "homepage": "https://centaur.run",
- "repository": "https://github.com/paradigmxyz/centaur",
- "license": "Apache-2.0 OR MIT",
- "keywords": ["centaur", "mcp", "tools", "agents"],
- "category": "developer-tools"
- }
- ]
- }
README.md · README · 260 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <img width="1500" height="500" alt="image" src="https://github.com/user-attachments/assets/cc85cdb1-5a72-4eb2-ba1b-2e0a8fbbf691" />
- <h4 align="center">
- Shared AI agents for teams.
- </h4>
- <p align="center">
- Talk to an agent in Slack, give it your tools, and let it run real work in a sandbox.
- </p>
- <p align="center">
- <a href="#features">Features</a> •
- <a href="#overview">Overview</a> •
- <a href="#getting-started">Getting Started</a> •
- <a href="#documentation">Documentation</a>
- </p>
- ## 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.
- ```text
- # 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:
- ```text
- 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
- ```text
- 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`](services/api-rs/) — Rust control plane for agents, tools, workflows, auth, and durable state
- - [`services/slackbotv2`](services/slackbotv2/) — Slack event handling and Slack delivery
- - [`services/sandbox`](services/sandbox/) — agent container image and harness adapter
- - [iron-proxy](https://docs.iron.sh) ([service](services/iron-proxy/)) — controlled outbound access and credential injection
- - [`tools`](tools/) — tool plugins
- - [`workflows`](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:
- ```bash
- /Users/magelinskaas/paradigmxyz/centaur
- ```
- Clone the repo and enter it:
- ```bash
- git clone <repo-url>
- cd centaur
- ```
- Install the local command runner:
- ```bash
- brew install just
- ```
- For a first-time local boot, Centaur needs these infrastructure secrets in your shell:
- ```bash
- 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:
- ```bash
- 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](https://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](https://docs.iron.sh) 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:
- ```bash
- just bootstrap-secrets
- just up
- ```
- After `just up` finishes, use Slack or the API examples in the [Developer Guide](AGENTS.md#e2e-testing-without-slack).
- For a more explicit path, see [Running Centaur on a Mac Mini-style setup](docs/pages/mac-mini-setup.mdx).
- 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.
- ```text
- 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:
- ```bash
- 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.
- ```python
- 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](https://docs.iron.sh)
- - 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](docs/pages/security.mdx) for the full threat model and the mechanisms behind each of these points, including known limitations like the shared credential vault.
- ## Documentation
- - [Docs app](docs/) — Vocs documentation source
- - [Quickstart](docs/pages/quickstart.mdx) — boot the local Kubernetes stack and run one agent turn
- - [Deploying in Production](docs/pages/deploying-in-production.mdx) — production secrets, Slack, Helm, and verification
- - [Architecture](docs/pages/architecture.mdx) — control plane, sandbox runtime, tools, workflows, and credential injection
- - [Developer Guide](AGENTS.md) — full local setup, architecture, API contracts, migrations, testing, and conventions
- - [Tools](tools/) — built-in tool plugins
- - [Workflows](workflows/) — external workflow plugins
- - [Agent plugin](plugins/centaur/) — connect Codex, Claude Code, and other MCP clients to Centaur
- - [API service](services/api-rs/) — Rust control plane
- - [Slackbot](services/slackbotv2/) — Slack integration
- - [Sandbox](services/sandbox/) — agent runtime image
- ## Contributing
- Before pushing changes, build and test the affected service locally:
- ```bash
- just build-one <service>
- just deploy
- ```
- For Python checks:
- ```bash
- uv run ruff check .
- uv run ruff format .
- uv run pytest
- ```
- See the [Developer Guide](AGENTS.md) for code conventions and end-to-end testing instructions.
- ## Acknowledgements
- Centaur builds on excellent open-source infrastructure, including Rust,
- [Axum](https://github.com/tokio-rs/axum), [Kubernetes](https://kubernetes.io/),
- [iron-proxy](https://docs.iron.sh), and the agent harnesses teams choose to run
- inside the sandbox.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.