Docker Deployment

Docker is the fastest way to get a reproducible Snippbot deployment. This guide covers the complete docker-compose.yml setup, first-run configuration, and ongoing maintenance commands.

Prerequisites

Docker 24+ and Docker Compose v2 (the docker compose plugin, not the legacy docker-compose binary)
An Anthropic API key (or other supported provider key)

docker-compose.yml

Create a file named docker-compose.yml in a directory of your choice (e.g. ~/snippbot/):

services:
  snippbot:
    image: ghcr.io/snippbot/snippbot:latest
    container_name: snippbot
    restart: unless-stopped
    ports:
      - "18781:18781"
      - "18790:18790"
    volumes:
      - snippbot-data:/root/.snippbot
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - SNIPPBOT_HOST=0.0.0.0
      - SNIPPBOT_PORT=18781
      - SNIPPBOT_LOG_LEVEL=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18781/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  snippbot-data:
    driver: local

Environment Variables

Create a .env file in the same directory to hold your secrets:

ANTHROPIC_API_KEY=sk-ant-your-key-here

Docker Compose automatically reads .env from the current directory and substitutes variables in docker-compose.yml.

All Supported Environment Variables

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	Yes*	—	Anthropic API key for Claude models
`OPENAI_API_KEY`	No	—	OpenAI API key (if using OpenAI models)
`SNIPPBOT_HOST`	No	`127.0.0.1`	Host address to bind the server to; set to `0.0.0.0` inside Docker
`SNIPPBOT_PORT`	No	`18781`	Port for the API and UI
`SNIPPBOT_LOG_LEVEL`	No	`info`	Logging verbosity: `debug`, `info`, `warning`, `error`
`SNIPPBOT_SECRET_KEY`	No	auto-generated	Secret key for session signing; set explicitly for multi-instance deployments

*Required unless another provider key is configured.

Running Snippbot

Start the container
Start in detached mode
```
docker compose up -d
```
Docker pulls the image (first run only) and starts the container. The -d flag runs it in the background.
Complete first-run setup

Open your browser and visit:
```
http://localhost:18781/setup
```
The setup wizard guides you through:
- Creating your admin account
- Confirming your API key is working
- Creating your first agent
Verify the health check
Check container health
```
docker compose ps
```
The STATUS column should show Up (healthy) after about 30 seconds.

Data Persistence

All Snippbot data (the SQLite database, agent workspaces, config files, and uploaded files) is stored in the named volume snippbot-data, which maps to /root/.snippbot inside the container.

To find where Docker stores the volume on your host:

docker volume inspect snippbot_snippbot-data

Backing up data

docker run --rm \
  -v snippbot_snippbot-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/snippbot-backup-$(date +%Y%m%d).tar.gz -C /data .

Restoring from backup

docker compose down
docker run --rm \
  -v snippbot_snippbot-data:/data \
  -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/snippbot-backup-20260301.tar.gz -C /data"
docker compose up -d

Updating Snippbot

docker compose pull && docker compose up -d

This downloads the latest image and recreates the container with zero data loss. The snippbot-data volume persists across container recreation.

Useful Commands

View logs

docker compose logs -f snippbot

docker compose logs --tail=100 snippbot

Open a shell inside the container

docker compose exec snippbot bash

This gives you a shell where you can run snippbot CLI commands directly:

snippbot status
snippbot config show

Stop and remove the container

docker compose down

docker compose down -v

Channel Adapter in Docker

The channel adapter runs as a separate process inside the same container. Port 18790 is already mapped in the docker-compose.yml above. To start the adapter:

docker compose exec snippbot snippbot channel start

Or add it as a second service that shares the same data volume:

services:
  snippbot:
    image: ghcr.io/snippbot/snippbot:latest
    # ... (same as above)

  snippbot-channels:
    image: ghcr.io/snippbot/snippbot:latest
    container_name: snippbot-channels
    restart: unless-stopped
    command: ["snippbot", "channel", "start"]
    ports:
      - "18790:18790"
    volumes:
      - snippbot-data:/root/.snippbot
    environment:
      - SNIPPBOT_HOST=0.0.0.0
    depends_on:
      snippbot:
        condition: service_healthy

volumes:
  snippbot-data:

Putting It Behind a Reverse Proxy

For production, place Snippbot behind nginx or Caddy to handle HTTPS. See the Reverse Proxy guide for complete configuration examples.

The key change is to not expose port 18781 publicly — let your reverse proxy handle TLS and proxy traffic internally:

ports:
  - "127.0.0.1:18781:18781"   # Only accessible on localhost
  - "127.0.0.1:18790:18790"   # Channel adapter, localhost only