Docker Deployment

Run Wraith Browser as a Docker container — single binary or with Redis for caching

Quick Start (Single Binary)

The fastest way to run Wraith Browser is a single Docker container. No external dependencies are required.

docker pull wraith/browser:latest

Run in stdio mode (MCP clients)

Most MCP clients (Claude Desktop, Claude Code) communicate over stdin/stdout. Mount your config directory so the knowledge cache and vault persist between runs:

docker run --rm -i \
  -v ~/.wraith:/root/.wraith \
  wraith/browser:latest \
  serve --transport stdio

Run in HTTP mode (remote access)

To expose the MCP server over HTTP for remote clients:

docker run -d \
  --name wraith \
  -p 3100:3100 \
  -v ~/.wraith:/root/.wraith \
  -e RUST_LOG="info" \
  wraith/browser:latest \
  serve --transport sse --host 0.0.0.0 --port 3100

Build from Source

If you prefer to build the image yourself:

git clone https://github.com/nicholasgasior/wraith-browser.git
cd wraith-browser
docker build -t wraith-browser:latest -f deploy/Dockerfile .

The multi-stage Dockerfile uses rust:1.78-slim for the build stage and debian:bookworm-slim for the runtime image. The final image contains only the compiled binary, CA certificates, and OpenSSL -- roughly 30 MB.

Docker Compose (with Redis)

Redis is optional. It enables persistent caching of page snapshots and extracted content, which can significantly speed up repeated visits and reduce bandwidth.

Create a docker-compose.yml:

services:
  wraith:
    image: wraith/browser:latest
    ports:
      - "3100:3100"
    environment:
      RUST_LOG: "info"
      REDIS_URL: "redis://redis:6379"
    command: ["./wraith-browser", "serve", "--transport", "sse", "--host", "0.0.0.0", "--port", "3100"]
    volumes:
      - ~/.wraith:/root/.wraith
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

volumes:
  redisdata:

Start the stack:

docker compose up -d

Tear down and remove volumes:

docker compose down -v

Environment Variables

Pass environment variables with -e flags or in the environment block of your Compose file. See the full list in the Configuration reference.

Variable	Purpose	Default
`RUST_LOG`	Log level filter	`wraith=info,tower_http=warn`
`REDIS_URL`	Redis connection string (enables caching)	(none)
`WRAITH_PROXY`	HTTP/SOCKS5 proxy URL	(none)
`WRAITH_FLARESOLVERR`	FlareSolverr endpoint for challenge pages	(none)

Health Check

Verify the server is running:

# HTTP mode — curl the SSE endpoint
curl http://localhost:3100/sse

# stdio mode — send an MCP initialize request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' \
  | docker run --rm -i wraith/browser:latest serve --transport stdio

Reverse Proxy

For production deployments, place Wraith behind nginx or Caddy for TLS termination:

server {
    listen 443 ssl;
    server_name wraith.example.com;

    ssl_certificate     /etc/ssl/certs/wraith.pem;
    ssl_certificate_key /etc/ssl/private/wraith.key;

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE requires these settings
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
    }
}

Data Directory

Wraith stores local state in ~/.wraith/:

Path	Contents
`~/.wraith/vault.db`	Encrypted credential vault
`~/.wraith/knowledge/`	Page cache and knowledge store
`~/.wraith/fingerprints/`	Saved browser fingerprint profiles

Mount this directory as a volume to persist data across container restarts.

Docker Deployment

On this page