# Add Carapace to Discord

## Outcome

Connect Carapace to Discord so inbound messages can trigger agent responses.

## Prerequisites

- `cara` installed.
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
- Discord bot token (`DISCORD_BOT_TOKEN`).
- Discord bot added to your server.
- Message Content Intent enabled in the Discord developer portal.
- A Discord channel ID for a test channel (recommended for send-path verification).

## 1) Create config

Generate a gateway token:

```bash
export CARAPACE_GATEWAY_TOKEN="$(openssl rand -hex 32)"
```

Windows (PowerShell) alternative:

```powershell
$bytes = [byte[]]::new(32)
[System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
$env:CARAPACE_GATEWAY_TOKEN = [System.BitConverter]::ToString($bytes).Replace('-', '').ToLower()
```

```json5
{
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "${CARAPACE_GATEWAY_TOKEN}"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic:claude-sonnet-4-6"
    }
  },
  "anthropic": {
    "apiKey": "${ANTHROPIC_API_KEY}"
  },
  "discord": {
    "botToken": "${DISCORD_BOT_TOKEN}",
    "gatewayEnabled": true,
    "gatewayIntents": 37377  // GUILDS | GUILD_MESSAGES | MESSAGE_CONTENT | DIRECT_MESSAGES
  }
}
```

If using OpenAI, swap the provider block and model:

```json5
"agents": {
  "defaults": {
    "model": "openai:gpt-5.5"
  }
},
"openai": {
  "apiKey": "${OPENAI_API_KEY}"
}
```

## 2) Run commands

```bash
CARAPACE_CONFIG_PATH=./carapace.json5 cara
```

Optional status check:

```bash
cara status --port 18789
curl -H "Authorization: Bearer ${CARAPACE_GATEWAY_TOKEN}" http://127.0.0.1:18789/health
```

Optional built-in verifier (sends a real test message):

```bash
cara verify --outcome discord --port 18789 --discord-to YOUR_CHANNEL_ID
```

Replace `YOUR_CHANNEL_ID` with the numeric Discord channel ID.

## 3) Verify

1. Send a message in a Discord channel where the bot is present.
2. Confirm Carapace receives it and sends a reply.
3. If you ran `cara verify`, confirm Discord checks report PASS.

## Next step

- [Trigger Cara from other apps](hooks-safe-automation.md)
- [Day-2 ops](../site/ops.md)

## Common failures and fixes

- Symptom: Bot sends messages but does not react to inbound messages.
  - Fix: Enable Message Content Intent and re-invite bot with correct scopes/intents.
- Symptom: No outbound responses at all.
  - Fix: Confirm `DISCORD_BOT_TOKEN` is valid and provider API key is configured.
- Symptom: Service starts but Discord remains disconnected.
  - Fix: Check logs for Discord gateway/auth errors and verify network egress to Discord.
