--- title: Quickstart description: Boot Centaur locally and verify the control plane. --- # Quickstart This guide gets you from a fresh checkout to a working local Centaur stack. You do not need a full production Kubernetes installation for local setup: a lightweight k3s-based cluster is enough. The happy path is: point `kubectl` at that cluster, bootstrap the required infra Secret, run `just up`, verify the API, then run one agent turn without Slack. If you want the easiest small-host path first, start with [Running Centaur on a Mac Mini-style setup](/mac-mini-setup). If you want an agent to drive setup with you, point it at these docs: every page is available through `/llms.txt`, `/llms-full.txt`, and static Markdown files such as `/md/quickstart.md`. ## 1. Install prerequisites From the repo root: ```bash brew install just kubectl helm jq ``` You also need Docker and a local Kubernetes cluster. This can be lightweight: k3s works on a small VPS, DigitalOcean droplet, Linux box, or Mac Mini-style host. Docker Desktop with Kubernetes enabled, kind, and minikube are also fine as long as `kubectl` points at that local cluster and it can run the Helm chart. The [Mac Mini-style setup guide](/mac-mini-setup) walks through the k3s path and includes notes for macOS/kind local evaluation. Check the target before booting Centaur: ```bash kubectl config current-context kubectl get nodes ``` The `Justfile` builds local images named `centaur-api-rs:latest`, `centaur-iron-proxy:latest`, `centaur-slackbotv2:latest`, and `centaur-agent:latest`, then deploys `contrib/chart` with `contrib/chart/values.dev.yaml`. ## 2. Export bootstrap secrets The default local chart expects one infra Secret named `centaur-infra-env`. `just bootstrap-secrets` creates it from your shell environment. `just bootstrap-secrets` currently requires these shell variables: ```bash export OP_SERVICE_ACCOUNT_TOKEN=... export OP_VAULT=... export SLACK_BOT_TOKEN=... export SLACK_SIGNING_SECRET=... export SLACKBOT_API_KEY=... ``` 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`. `OP_SERVICE_ACCOUNT_TOKEN` and `OP_VAULT` let [iron-proxy](https://docs.iron.sh) resolve model and tool credentials through 1Password. `SLACK_SIGNING_SECRET` and `SLACKBOT_API_KEY` are API boot requirements in the current chart. `SLACK_BOT_TOKEN` is required by the default local bootstrap because Slackbot is enabled in `values.dev.yaml`; use a real token if you want to test Slack. `SLACKBOT_API_KEY` is Slackbot's dedicated static service token. Console uses the existing JWT signing secret to mint its own short-lived, purpose-bound service tokens for api-rs. Application-level model and tool secrets, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `AMP_API_KEY`, and `GITHUB_TOKEN`, should live in 1Password or the configured [iron-proxy](https://docs.iron.sh) secret source. Sandboxes receive placeholder values and [iron-proxy](https://docs.iron.sh) injects the real credentials only on approved outbound requests. The default harness is `codex`, so `OPENAI_API_KEY` must exist in the configured secret source before Slack agent turns can complete. Use explicit harness selectors only when you want a non-default harness such as Amp or Claude Code. ## 3. Boot the stack ```bash just up ``` That runs: 1. `just bootstrap-secrets` 2. `just build` 3. `just deploy` Check the namespace: ```bash just status ``` The local bootstrap also creates the Console admin, API key, and encryption secrets. Before inviting more users or granting tools, review default roles and sandbox capabilities in [Advanced Permissioning](/secrets/advanced-permissioning#configure-the-console). ## 4. Verify the API The API exposes localhost inside its own deployment. Localhost bypasses external API-key auth, which is why the health check runs through `kubectl exec`: ```bash kubectl exec -n centaur deploy/centaur-centaur-api-rs -- \ curl -fsS http://localhost:8080/healthz ``` Expected shape: ```json {"status":"ok"} ``` ## 5. Run an agent turn Before testing Slack, run the local smoke test. It uses the same durable agent API that Slackbot uses: spawn or reuse a runtime, persist a message, enqueue an execution, and poll the execution state until the result contains `PONG`. ```bash just smoke ``` The successful result includes the terminal execution row. The important fields are: ```json { "status": "completed", "result_text": "...PONG..." } ``` If the smoke test times out or fails, start with the local stack state: ```bash just status just logs api kubectl get pods -n centaur -l centaur.ai/managed=true ``` If you changed the namespace or release name, set `CENTAUR_NAMESPACE` and `CENTAUR_RELEASE` before running `just smoke` so the recipe targets the right deployment. ## 6. Setup Slack integration Slack needs to reach the Slackbot webhook at a public HTTPS URL. Configure your network, ingress, or local tunnel so the Slackbot route is reachable at: ```text https:///api/webhooks/slack ``` In your Slack app's **Event Subscriptions** settings, set the Request URL to the Slackbot webhook URL above. To use Block Kit buttons or selects, enable **Interactivity & Shortcuts** and set its Request URL to the same Slackbot webhook URL. Each interaction is delivered to workflows as `slack.block_action.` with the selected value and sanitized Slack user, team, channel, thread, and message metadata. Subscribe to the `app_mention` bot event. For a minimal channel-mention test, the app also needs Bot Token Scopes that let it read mentions and write replies, for example `app_mentions:read` and `chat:write`. If you enable DM events such as `message.im`, Slack will also require direct-message scopes such as `im:history`. Scheduled task delivery to a user's DM requires `im:write`. Save changes and reinstall the app. ### Agent Messaging Experience Slackbot defaults to the existing messaging behavior. To use Slack's Agent messaging experience, set `slackbotv2.agentViewEnabled: true` in your Helm values, or `SLACKBOTV2_AGENT_VIEW_ENABLED=true` when running the service directly. The setting takes effect when the service restarts. Configure the Slack app with `features.agent_view` and an `agent_description`. For an existing Assistant app, replace `features.assistant_view` and its nested `assistant_description`. Keep the existing bot configuration, scopes, and event subscriptions. Include these scopes and bot events: ```yaml features: agent_view: agent_description: "An assistant for your team's work." suggested_prompts: - title: "Get Started" message: "What can you help me with?" oauth_config: scopes: bot: - assistant:write - chat:write - im:history - im:read - users:read settings: event_subscriptions: bot_events: - app_mention - message.im - app_home_opened - agent_session_stopped ``` This is a fragment to merge into your app manifest. Reinstall the app if its scopes change, and refresh Slack after switching the experience. Slack's manifest migration is irreversible. The service toggle does not change the manifest or restore Slack's old UI. Keep the service setting matched to the app, and test the migration with a separate development app first. In Agent mode, each new top-level DM starts its own session. Replies continue that thread's session without a mention. Channel replies still require a mention. Existing DM thread replies retain their thread identity. Older conversation-wide DM subscriptions do not override Agent mode's thread roots. Streaming progress and titles continue through the existing renderer. With `agent_session_stopped` subscribed, Slack shows a Stop button that interrupts the running execution, like the mentioned `stop` command. Without that subscription, Slack shows a loading indicator without a Stop button. Suggested prompts can be configured statically in the manifest. Context-aware prompts and synchronization of user-edited Slack session titles are separate integrations. See Slack's [migration guide](https://docs.slack.dev/ai/migrating-to-agent-messaging/) for the app-side rollout requirements. ## 7. Try Slack mentions Invite the bot to a test channel and mention it: ```text /invite @ @ reply with exactly PONG ``` Slack messages without a harness flag use Codex. Add a selector such as `--amp`, `--claude`, or `--pi` only when you want to override the default. If Slack receives the mention but no agent runs, inspect Slackbot logs: ```bash just logs slackbot ``` You should see `POST /api/webhooks/slack`.