# Centaur Mental Model Wiki

> Centaur is a self-hosted Kubernetes agent platform that lets teams share one AI agent accessed via Slack or API, running each conversation in an isolated sandbox with durable state, approved tool plugins, and credential-safe egress through iron-proxy.

This is a Grok-Wiki source-grounded repository wiki. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown wiki](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2.md)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2)
- [GitHub repository](https://github.com/paradigmxyz/centaur)

## Repository

- Repository: paradigmxyz/centaur

- Generated: 2026-05-21T23:46:21.175Z
- Updated: 2026-05-21T23:46:27.274Z
- Runtime: Claude Code
- Format: Mental Model
- Pages: 8

## Pages

- [How Centaur Works in Your Head](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/pages/01-how-centaur-works-in-your-head.md): The simplest mental model of Centaur: one shared agent, one sandbox per Slack thread, durable state so nothing is lost on restart, and iron-proxy so agents never touch raw credentials. Understand this page and every other page falls into place.
- [Durability Invariants & Failure Modes](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/pages/02-durability-invariants-failure-modes.md): What Postgres owns, what lives only in-process, how reconnects and pod replacements are safe, and the exact failure scenarios where state can be lost or replayed incorrectly. The distinction between the event stream (client contract) and in-memory runtime state is the critical boundary.
- [API Lifecycle: spawn → message → execute → events → release](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/pages/03-api-lifecycle-spawn-message-execute-events-release.md): The five-step durable API lifecycle, how each call maps to a Postgres write, what the SSE event stream guarantees, and what happens when a client reconnects mid-run with after_event_id. Also covers the Slackbot ingress path including HMAC signature verification.
- [Sandbox Pods & the Warm Pool](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/pages/04-sandbox-pods-the-warm-pool.md): How sandbox Kubernetes pods are created, claimed, and recycled; why the warm pool exists (15-second startup cost); the POOL_EVICT_ON_STARTUP invariant that guarantees new pods run fresh code after a deploy; and the sandbox session state machine (idle → running → delivering → released).
- [Harness Adapters: Amp, Claude Code, Codex, pi-mono](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/pages/05-harness-adapters-amp-claude-code-codex-pi-mono.md): How the harness_protocol layer normalizes four different agent CLIs into a single event stream. What each adapter does differently (Amp materializes attachments to files; Claude Code passes Anthropic content blocks directly; Codex/pi-mono extract plain text). The _VALID_STDOUT_EVENT_TYPES allowlist as a forward-compatibility boundary.
- [Tool Plugin Model: Discovery, Secrets, & the centaur_sdk](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/pages/06-tool-plugin-model-discovery-secrets-the-centaur_sdk.md): How tools are discovered (Python files in tools/ or overlays), loaded by tool_manager.py, and exposed to sandboxes. The ToolContext / secret() resolution chain (tool context → pluggable backend → default). The SecretMode enum (replace vs inject). How tool authors import centaur_sdk and never see raw credentials.
- [Durable Workflow Engine: Checkpoint/Replay](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/pages/07-durable-workflow-engine-checkpoint-replay.md): The checkpoint/replay model inspired by Cloudflare Workflows: the handler function IS the workflow, ctx.step() calls are discovered at runtime, and Postgres checkpoints each step result. On resume after a crash the handler re-executes top-to-bottom but skips already-checkpointed steps instantly. How this enables sleep, suspension, child agents, and idempotent re-runs.
- [Secrets & Egress: iron-proxy as the Trust Boundary](https://grok-wiki.com/public/wiki/paradigmxyz-centaur-57fc6b2755e2/pages/08-secrets-egress-iron-proxy-as-the-trust-boundary.md): How iron-proxy is the single egress choke point for every sandbox, why it is per-sandbox rather than shared (a compromised pod cannot leak into another), the four secret transform types (replace, inject, gcp_auth, oauth_token, hmac_sign), the NetworkPolicy default-deny invariant, and what changes break the security model (shared proxy, raw key injection, relaxed NetworkPolicy).

## Source Files

- `AGENTS.md`
- `centaur_sdk/backends/base.py`
- `centaur_sdk/backends/registry.py`
- `centaur_sdk/tests/test_tool_sdk.py`
- `centaur_sdk/tool_sdk.py`
- `docs/pages/architecture.mdx`
- `docs/pages/security.mdx`
- `docs/pages/what-is-centaur.mdx`
- `README.md`
- `services/api/api/agent.py`
- `services/api/api/app.py`
- `services/api/api/iron-proxy.base.yaml`
- `services/api/api/models.py`
- `services/api/api/proxy_config.py`
- `services/api/api/runtime_control.py`
- `services/api/api/sandbox/base.py`
- `services/api/api/sandbox/harness_protocol.py`
- `services/api/api/sandbox/kubernetes.py`
- `services/api/api/sandbox/normalize.py`
- `services/api/api/sandbox/prompt_assembly.py`
- `services/api/api/sandbox/registry.py`
- `services/api/api/slackbot_client.py`
- `services/api/api/tool_manager.py`
- `services/api/api/warm_pool.py`
- `services/api/api/workflow_engine.py`
- `services/api/tests/test_agent_resilience.py`
- `services/api/tests/test_amp_wrapper.py`
- `services/api/tests/test_harness_protocol.py`
- `services/api/tests/test_inflight_replay.py`
- `services/api/tests/test_proxy_config.py`
- `services/api/tests/test_warm_pool.py`
- `services/api/tests/test_workflow_engine_title.py`
- `services/api/tests/test_workflow_idempotency_unit.py`
- `workflows/paradigm_pulse_daily.py`
- `workflows/slack_sync.py`