Skip to content
Back to search

centaur

MarketplaceWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/paradigmxyz--centaur/badge.svg)](/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)

  1. {
  2. "name": "centaur",
  3. "owner": {
  4. "name": "Paradigm",
  5. "url": "https://github.com/paradigmxyz"
  6. },
  7. "description": "Official Centaur plugins for agent clients.",
  8. "version": "0.1.0",
  9. "plugins": [
  10. {
  11. "name": "centaur",
  12. "displayName": "Centaur",
  13. "source": "./plugins/centaur",
  14. "description": "Use your team's approved Centaur tools through MCP.",
  15. "version": "0.1.0",
  16. "author": {
  17. "name": "Paradigm",
  18. "url": "https://github.com/paradigmxyz"
  19. },
  20. "homepage": "https://centaur.run",
  21. "repository": "https://github.com/paradigmxyz/centaur",
  22. "license": "Apache-2.0 OR MIT",
  23. "keywords": ["centaur", "mcp", "tools", "agents"],
  24. "category": "developer-tools"
  25. }
  26. ]
  27. }
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)

  1. <img width="1500" height="500" alt="image" src="https://github.com/user-attachments/assets/cc85cdb1-5a72-4eb2-ba1b-2e0a8fbbf691" />
  2. <h4 align="center">
  3. Shared AI agents for teams.
  4. </h4>
  5. <p align="center">
  6. Talk to an agent in Slack, give it your tools, and let it run real work in a sandbox.
  7. </p>
  8. <p align="center">
  9. <a href="#features">Features</a> •
  10. <a href="#overview">Overview</a> •
  11. <a href="#getting-started">Getting Started</a> •
  12. <a href="#documentation">Documentation</a>
  13. </p>
  14. ## Features
  15. - **Slack-native agent conversations**: mention the bot in Slack and get progress plus final answers back in the thread.
  16. - **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.
  17. - **Bring your own harness**: run CLI-based agents such as Amp, Claude Code, Codex, or deployment-specific harnesses.
  18. - **Shared tools**: add Python tool plugins once and make them available to every agent conversation.
  19. - **Durable workflows**: run jobs that can sleep, resume, wait for events, start child agents, and survive service restarts.
  20. - **Credential boundaries**: agents can use approved services without receiving raw API keys in their environment.
  21. - **Replayable state**: messages, executions, events, and delivery state are stored so clients can reconnect without losing the result.
  22. - **Organization overlays**: layer in your own tools, workflows, personas, skills, and prompts without forking the base platform.
  23. ...and a lot more.
  24. ## Overview
  25. Centaur is a self-hosted agent platform for teams that want one shared agent instead of many one-off local setups.
  26. ```text
  27. # 1. Ask from Slack.
  28. @centaur can you figure out why the billing tests are failing?
  29. # 2. Centaur assigns a sandbox for the thread.
  30. # The agent can inspect code, run commands, and call approved tools.
  31. # 3. Progress and the final answer are delivered back to Slack.
  32. ```
  33. You can also drive Centaur directly through the API:
  34. ```text
  35. POST /api/session/{thread_key} # create or reuse a session
  36. POST /api/session/{thread_key}/messages # store the user turn
  37. POST /api/session/{thread_key}/execute # start the agent
  38. GET /api/session/{thread_key}/events # stream or replay output
  39. ```
  40. The platform handles sandbox lifecycle, durable transcript storage, tool access, credential injection, workflow execution, and final delivery.
  41. ## What Centaur Is Good For
  42. - investigating CI failures
  43. - answering questions with internal tools
  44. - summarizing Slack threads or customer context
  45. - running recurring checks and digests
  46. - coordinating multi-step operational workflows
  47. - giving agents access to a real repo and test environment
  48. - standardizing agent behavior across a team
  49. ## How It Works
  50. ```text
  51. Slack or API
  52. |
  53. v
  54. Centaur API
  55. |
  56. +-- Postgres durable state
  57. +-- tool metadata and workflow runtime
  58. +-- sandbox assignment
  59. |
  60. v
  61. Kubernetes sandbox
  62. |
  63. +-- agent harness
  64. +-- workspace and shell
  65. +-- local tool CLI shims
  66. |
  67. v
  68. Controlled outbound access
  69. ```
  70. The main directories are:
  71. - [`services/api-rs`](services/api-rs/) — Rust control plane for agents, tools, workflows, auth, and durable state
  72. - [`services/slackbotv2`](services/slackbotv2/) — Slack event handling and Slack delivery
  73. - [`services/sandbox`](services/sandbox/) — agent container image and harness adapter
  74. - [iron-proxy](https://docs.iron.sh) ([service](services/iron-proxy/)) — controlled outbound access and credential injection
  75. - [`tools`](tools/) — tool plugins
  76. - [`workflows`](workflows/) — workflow plugins
  77. ## Getting Started
  78. Centaur runs locally on Kubernetes, but local setup does not require a full
  79. production Kubernetes installation. A lightweight k3s cluster on a small
  80. always-on host is enough. The expected local checkout path is:
  81. ```bash
  82. /Users/magelinskaas/paradigmxyz/centaur
  83. ```
  84. Clone the repo and enter it:
  85. ```bash
  86. git clone <repo-url>
  87. cd centaur
  88. ```
  89. Install the local command runner:
  90. ```bash
  91. brew install just
  92. ```
  93. For a first-time local boot, Centaur needs these infrastructure secrets in your shell:
  94. ```bash
  95. export OP_SERVICE_ACCOUNT_TOKEN=...
  96. export OP_VAULT=...
  97. export SLACK_BOT_TOKEN=...
  98. export SLACK_SIGNING_SECRET=...
  99. export SLACKBOT_API_KEY=...
  100. ```
  101. To boot optional Teams ingress locally, also export:
  102. ```bash
  103. export TEAMS_BOT_APP_ID=...
  104. export TEAMS_BOT_APP_PASSWORD=...
  105. export TEAMS_BOT_APP_TENANT_ID=...
  106. # TEAMSBOT_API_KEY is generated by bootstrap when omitted.
  107. ```
  108. Create the Slackbot app at [api.slack.com/apps](https://api.slack.com/apps).
  109. Use the app's Bot User OAuth Token for `SLACK_BOT_TOKEN` and its Signing Secret
  110. for `SLACK_SIGNING_SECRET`.
  111. What they are for:
  112. - `OP_SERVICE_ACCOUNT_TOKEN`: lets [iron-proxy](https://docs.iron.sh) resolve 1Password-backed runtime secrets
  113. - `OP_VAULT`: the 1Password vault name or id to read from
  114. - `SLACK_BOT_TOKEN`: Slack bot token for the local Slackbot service
  115. - `SLACK_SIGNING_SECRET`: verifies incoming Slack requests
  116. - `SLACKBOT_API_KEY`: API key the Slackbot uses to call Centaur
  117. - `CENTAUR_APIRS_ADMIN_API_KEY`: optional static bearer token with full access to api-rs
  118. - `CENTAUR_JWT_SIGNING_SECRET`: signs short-lived Console and sandbox JWTs accepted by api-rs
  119. - `TEAMS_BOT_APP_ID`, `TEAMS_BOT_APP_PASSWORD`, `TEAMS_BOT_APP_TENANT_ID`: optional Teams ingress app credentials when `teamsbot.enabled=true`
  120. - `TEAMSBOT_API_KEY`: API key the Teamsbot uses to call Centaur; generated by local bootstrap when Teams credentials are present and this is omitted
  121. Then create local Kubernetes Secrets from those environment variables and boot the stack:
  122. ```bash
  123. just bootstrap-secrets
  124. just up
  125. ```
  126. After `just up` finishes, use Slack or the API examples in the [Developer Guide](AGENTS.md#e2e-testing-without-slack).
  127. For a more explicit path, see [Running Centaur on a Mac Mini-style setup](docs/pages/mac-mini-setup.mdx).
  128. It covers k3s on a small VPS, DigitalOcean droplet, Linux box, or Mac
  129. Mini-style host.
  130. ## Tools
  131. 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.
  132. ```text
  133. tools/my_tool/
  134. ├── __init__.py
  135. ├── client.py
  136. ├── cli.py
  137. ├── .env.example
  138. └── pyproject.toml
  139. ```
  140. Each runtime tool should declare a `[project.scripts]` entry so sandbox startup
  141. can install it as a local CLI shim. Agents discover installed tools with:
  142. ```bash
  143. centaur-tools list
  144. my-tool --help
  145. ```
  146. Workflow handlers can still invoke tools through `ctx.call_tool(...)`; the
  147. workflow host uses the generated `centaur-tools` bridge for that compatibility
  148. path. api-rs does not expose legacy HTTP tool-method routes as the current
  149. sandbox tool registry.
  150. ## Workflows
  151. Workflows are Python functions with durable steps.
  152. ```python
  153. WORKFLOW_NAME = "daily_digest"
  154. async def handler(inp, ctx):
  155. data = await ctx.step("collect", lambda: collect_digest_data(inp))
  156. summary = await ctx.run_agent("summarize", text=f"Summarize this: {data}")
  157. return {"summary": summary}
  158. ```
  159. Use workflows when a task should run longer than one request, wait for something external, run on a schedule, or coordinate multiple agent turns.
  160. ## Security Model
  161. Centaur is designed around practical isolation and auditability:
  162. - each conversation runs in a Kubernetes sandbox with a default-deny NetworkPolicy
  163. - sandboxes call approved local tool CLI shims and reach the outside world only through a per-sandbox [iron-proxy](https://docs.iron.sh)
  164. - 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
  165. - messages, executions, events, and delivery state are persisted
  166. - outbound activity can be audited
  167. 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.
  168. ## Documentation
  169. - [Docs app](docs/) — Vocs documentation source
  170. - [Quickstart](docs/pages/quickstart.mdx) — boot the local Kubernetes stack and run one agent turn
  171. - [Deploying in Production](docs/pages/deploying-in-production.mdx) — production secrets, Slack, Helm, and verification
  172. - [Architecture](docs/pages/architecture.mdx) — control plane, sandbox runtime, tools, workflows, and credential injection
  173. - [Developer Guide](AGENTS.md) — full local setup, architecture, API contracts, migrations, testing, and conventions
  174. - [Tools](tools/) — built-in tool plugins
  175. - [Workflows](workflows/) — external workflow plugins
  176. - [Agent plugin](plugins/centaur/) — connect Codex, Claude Code, and other MCP clients to Centaur
  177. - [API service](services/api-rs/) — Rust control plane
  178. - [Slackbot](services/slackbotv2/) — Slack integration
  179. - [Sandbox](services/sandbox/) — agent runtime image
  180. ## Contributing
  181. Before pushing changes, build and test the affected service locally:
  182. ```bash
  183. just build-one <service>
  184. just deploy
  185. ```
  186. For Python checks:
  187. ```bash
  188. uv run ruff check .
  189. uv run ruff format .
  190. uv run pytest
  191. ```
  192. See the [Developer Guide](AGENTS.md) for code conventions and end-to-end testing instructions.
  193. ## Acknowledgements
  194. Centaur builds on excellent open-source infrastructure, including Rust,
  195. [Axum](https://github.com/tokio-rs/axum), [Kubernetes](https://kubernetes.io/),
  196. [iron-proxy](https://docs.iron.sh), and the agent harnesses teams choose to run
  197. inside the sandbox.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.