Discord Docker Deployment

PocketPaw ships with a dedicated Discord deployment setup in deploy/discord/. This runs the bot headless (no web dashboard) in a lightweight container with all agent backends and tools pre-installed.

Quick Start

cd deploy/discord
cp .env.example .env
# Edit .env with your bot token and LLM provider
docker compose up -d

LLM Provider Options

The .env.example file includes six provider options. Uncomment the one that fits your setup.

POCKETPAW_AGENT_BACKEND=claude_agent_sdk
POCKETPAW_CLAUDE_SDK_PROVIDER=litellm
POCKETPAW_LITELLM_API_BASE=http://host.docker.internal:4000
POCKETPAW_LITELLM_API_KEY=your-litellm-master-key
POCKETPAW_LITELLM_MODEL=anthropic/claude-sonnet-4-6

POCKETPAW_AGENT_BACKEND=claude_agent_sdk
POCKETPAW_CLAUDE_SDK_PROVIDER=anthropic
POCKETPAW_ANTHROPIC_API_KEY=sk-ant-...

# On your local machine first:
claude setup-token

# Then in .env:
POCKETPAW_AGENT_BACKEND=claude_agent_sdk
POCKETPAW_CLAUDE_SDK_PROVIDER=claude_code
POCKETPAW_CLAUDE_CODE_OAUTH_TOKEN={"accessToken":"sk-ant-oat01-...","refreshToken":"sk-ant-ort01-...","expiresAt":"2027-..."}

POCKETPAW_AGENT_BACKEND=claude_agent_sdk
POCKETPAW_CLAUDE_SDK_PROVIDER=claude_code

POCKETPAW_AGENT_BACKEND=claude_agent_sdk
POCKETPAW_CLAUDE_SDK_PROVIDER=openai_compatible
POCKETPAW_OPENAI_COMPATIBLE_BASE_URL=http://host.docker.internal:8080/v1
POCKETPAW_OPENAI_COMPATIBLE_API_KEY=your-api-key
POCKETPAW_OPENAI_COMPATIBLE_MODEL=your-model

POCKETPAW_AGENT_BACKEND=openai_agents
POCKETPAW_OPENAI_AGENTS_PROVIDER=litellm
POCKETPAW_LITELLM_API_BASE=http://host.docker.internal:4000
POCKETPAW_LITELLM_API_KEY=your-litellm-master-key
POCKETPAW_LITELLM_MODEL=openai/gpt-5.2

Dockerfile

The Discord Dockerfile uses a multi-stage build optimized for headless operation (no Playwright/Chromium):

Node stage (node:22-slim):

• Installs Claude Code CLI and Codex CLI globally

Builder stage (python:3.12-slim):

• Creates a virtual environment and installs pocketpaw[all]

Runtime stage (python:3.12-slim):

• Copies Node.js, CLI tools, and the Python venv
• Installs only runtime deps (git, tesseract)
• Creates a non-root pocketpaw user
• Pre-creates ~/.claude.json marker file (prevents Claude Code onboarding prompt)
• Runs pocketpaw --discord as the entrypoint

Docker Compose

The docker-compose.yaml defines a single pocketpaw-discord service with four volume mounts:

volumes:
  # PocketPaw config, memory, sessions, audit logs
  - pocketpaw-discord-data:/home/pocketpaw/.pocketpaw

  # Custom identity / system prompt (optional)
  - ./identity:/home/pocketpaw/.pocketpaw/identity

  # Agent-created files (accessible on the host)
  - ./workspace:/home/pocketpaw/workspace

  # Claude Code OAuth credentials
  - claude-auth:/home/pocketpaw/.claude

Claude Auth Volume

The claude-auth volume stores Claude Code OAuth credentials. Two options:

Named volume (for Coolify and remote servers):

- claude-auth:/home/pocketpaw/.claude

Exec into the container once to run claude and complete the login, or use the OAuth token approach.

Host bind mount (reuse your local Claude Code login):

- ${CLAUDE_CONFIG_DIR:-~/.claude}:/home/pocketpaw/.claude

Resource Limits

The compose file sets resource limits to prevent runaway usage:

Adjust these in the deploy.resources section based on your server.

Discord Configuration

Required

POCKETPAW_DISCORD_BOT_TOKEN=your-bot-token-here

Access Control

# Lock to specific servers
POCKETPAW_DISCORD_ALLOWED_GUILD_IDS=[123456789012345678]

# Restrict to specific channels
POCKETPAW_DISCORD_ALLOWED_CHANNEL_IDS=[123456789012345678]

# Restrict to specific users
POCKETPAW_DISCORD_ALLOWED_USER_IDS=[123456789012345678]

Server-Wide Conversation Mode

Enable conversation mode across all channels without needing the /converse command:

POCKETPAW_DISCORD_CONVERSATION_ALL_CHANNELS=true

# Exclude channels like announcements or rules
POCKETPAW_DISCORD_CONVERSATION_EXCLUDE_CHANNEL_IDS=[123456789,987654321]

Bot Presence

POCKETPAW_DISCORD_BOT_NAME=CodeReviewer
POCKETPAW_DISCORD_STATUS_TYPE=online          # online, idle, dnd, invisible
POCKETPAW_DISCORD_ACTIVITY_TYPE=watching      # playing, streaming, listening, watching
POCKETPAW_DISCORD_ACTIVITY_TEXT=your code

Soul (Persistent Identity)

Give your bot a persistent personality that evolves over time:

POCKETPAW_SOUL_ENABLED=true
POCKETPAW_SOUL_NAME=Paw
POCKETPAW_SOUL_ARCHETYPE=The Helpful Assistant
POCKETPAW_SOUL_AUTO_SAVE_INTERVAL=300

Managing the Container

# View logs
docker compose logs -f pocketpaw-discord

# Restart
docker compose restart pocketpaw-discord

# Stop
docker compose down

# Rebuild after updates
docker compose build && docker compose up -d

Coolify Deployment

For Coolify users:

1. Point to the deploy/discord/ directory in your repo
2. Set the Dockerfile path to deploy/discord/Dockerfile and build context to the repo root
3. Add all env vars from .env.example in the Coolify environment settings
4. For Claude Code auth, use the OAuth token option (POCKETPAW_CLAUDE_CODE_OAUTH_TOKEN) to avoid interactive login, or use the container terminal to run claude once

Related