Docker - SimpleClaw

SimpleClaw can be deployed in Docker containers for isolated, reproducible environments.

Overview

Docker deployment provides:

Isolated environment - no local Node.js installation required
Reproducible builds - consistent behavior across systems
Easy updates - pull new images to upgrade
Resource limits - control memory and CPU usage
Multi-container setup - gateway + CLI in separate containers

Quick Start

Using Docker Compose

Create docker-compose.yml:

services:
  simpleclaw-gateway:
    image: simpleclaw:latest
    environment:
      HOME: /home/node
      SIMPLECLAW_GATEWAY_TOKEN: ${SIMPLECLAW_GATEWAY_TOKEN}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    volumes:
      - ./config:/home/node/.simpleclaw
      - ./workspace:/home/node/.simpleclaw/workspace
    ports:
      - "18789:18789"
    restart: unless-stopped
    command:
      - node
      - dist/index.js
      - gateway
      - --bind
      - lan
      - --port
      - "18789"

Create .env file:

SIMPLECLAW_GATEWAY_TOKEN=your-secure-token
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456:ABC...
DISCORD_BOT_TOKEN=MTk...

Start the gateway:

docker compose up -d

Check status:

docker compose logs -f

Building the Image

From Repository

Clone and build:

git clone https://github.com/simpleclaw/simpleclaw.git
cd simpleclaw

# Build standard image
docker build -t simpleclaw:local .

# Build with browser support (adds ~300MB)
docker build \
  --build-arg SIMPLECLAW_INSTALL_BROWSER=1 \
  -t simpleclaw:browser \
  .

# Build with custom apt packages
docker build \
  --build-arg SIMPLECLAW_DOCKER_APT_PACKAGES="vim curl" \
  -t simpleclaw:custom \
  .

Dockerfile Overview

The Dockerfile:

Base: node:22-bookworm (Debian 12)
User: node (uid 1000, non-root)
Installs: Bun, pnpm, project dependencies
Builds: TypeScript to dist/, UI to ui/dist/
Optional: Chromium + Xvfb (if SIMPLECLAW_INSTALL_BROWSER=1)
Exposes: Port 18789 (gateway)
Command: node simpleclaw.mjs gateway --allow-unconfigured

Build Arguments

Argument	Purpose	Example
`SIMPLECLAW_INSTALL_BROWSER`	Install Chromium + Xvfb	`--build-arg SIMPLECLAW_INSTALL_BROWSER=1`
`SIMPLECLAW_DOCKER_APT_PACKAGES`	Additional apt packages	`--build-arg SIMPLECLAW_DOCKER_APT_PACKAGES="vim curl"`

Running Containers

Gateway Container

Run the gateway:

docker run -d \
  --name simpleclaw-gateway \
  -p 18789:18789 \
  -v $(pwd)/config:/home/node/.simpleclaw \
  -v $(pwd)/workspace:/home/node/.simpleclaw/workspace \
  -e SIMPLECLAW_GATEWAY_TOKEN=your-token \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  simpleclaw:latest

CLI Container

Run CLI commands:

docker run --rm \
  -v $(pwd)/config:/home/node/.simpleclaw \
  -e SIMPLECLAW_GATEWAY_TOKEN=your-token \
  simpleclaw:latest \
  node dist/index.js channels status

Interactive Shell

Drop into a shell:

docker run --rm -it \
  -v $(pwd)/config:/home/node/.simpleclaw \
  simpleclaw:latest \
  /bin/bash

Configuration

Volume Mounts

Mount these directories:

-v /host/config:/home/node/.simpleclaw         # Config and credentials
-v /host/workspace:/home/node/.simpleclaw/workspace  # Agent workspace

Environment Variables

Pass via -e or .env file:

HOME=/home/node                    # User home directory
NODE_ENV=production                # Production mode
SIMPLECLAW_GATEWAY_TOKEN=...       # Gateway auth token
SIMPLECLAW_GATEWAY_BIND=lan        # Bind address (lan/loopback)
SIMPLECLAW_GATEWAY_PORT=18789      # Gateway port
ANTHROPIC_API_KEY=...              # Anthropic API key
TELEGRAM_BOT_TOKEN=...             # Telegram bot token
DISCORD_BOT_TOKEN=...              # Discord bot token
CLAUDE_AI_SESSION_KEY=...          # Claude.ai session
CLAUDE_WEB_SESSION_KEY=...         # Claude web session
CLAUDE_WEB_COOKIE=...              # Claude web cookie

Network Mode

Bind to specific interfaces:

# Loopback only (localhost)
docker run ... \
  simpleclaw:latest \
  node dist/index.js gateway --bind loopback

# LAN (all interfaces)
docker run ... \
  simpleclaw:latest \
  node dist/index.js gateway --bind lan

Docker Compose Configuration

Full Example

services:
  simpleclaw-gateway:
    image: ${SIMPLECLAW_IMAGE:-simpleclaw:latest}
    container_name: simpleclaw-gateway
    environment:
      HOME: /home/node
      TERM: xterm-256color
      NODE_ENV: production
      SIMPLECLAW_GATEWAY_TOKEN: ${SIMPLECLAW_GATEWAY_TOKEN}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
      DISCORD_BOT_TOKEN: ${DISCORD_BOT_TOKEN}
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY}
    volumes:
      - ${SIMPLECLAW_CONFIG_DIR:-./config}:/home/node/.simpleclaw
      - ${SIMPLECLAW_WORKSPACE_DIR:-./workspace}:/home/node/.simpleclaw/workspace
    ports:
      - "${SIMPLECLAW_GATEWAY_PORT:-18789}:18789"
      - "${SIMPLECLAW_BRIDGE_PORT:-18790}:18790"
    init: true
    restart: unless-stopped
    command:
      - node
      - dist/index.js
      - gateway
      - --bind
      - "${SIMPLECLAW_GATEWAY_BIND:-lan}"
      - --port
      - "18789"
      - --verbose

  simpleclaw-cli:
    image: ${SIMPLECLAW_IMAGE:-simpleclaw:latest}
    container_name: simpleclaw-cli
    environment:
      HOME: /home/node
      TERM: xterm-256color
      SIMPLECLAW_GATEWAY_TOKEN: ${SIMPLECLAW_GATEWAY_TOKEN}
      BROWSER: echo
    volumes:
      - ${SIMPLECLAW_CONFIG_DIR:-./config}:/home/node/.simpleclaw
      - ${SIMPLECLAW_WORKSPACE_DIR:-./workspace}:/home/node/.simpleclaw/workspace
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]

Environment File

Create .env:

SIMPLECLAW_IMAGE=simpleclaw:latest
SIMPLECLAW_CONFIG_DIR=./config
SIMPLECLAW_WORKSPACE_DIR=./workspace
SIMPLECLAW_GATEWAY_PORT=18789
SIMPLECLAW_BRIDGE_PORT=18790
SIMPLECLAW_GATEWAY_BIND=lan
SIMPLECLAW_GATEWAY_TOKEN=your-secure-token
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456:ABC...
DISCORD_BOT_TOKEN=MTk...

Run CLI Commands

# Check status
docker compose run --rm simpleclaw-cli channels status

# Send message
docker compose run --rm simpleclaw-cli message send \
  --to +1234567890 \
  --message "Hello from Docker"

# Talk to agent
docker compose run --rm simpleclaw-cli agent \
  --message "What's the weather?" \
  --thinking high

Browser Automation

With Chromium Pre-installed

Build with browser:

docker build \
  --build-arg SIMPLECLAW_INSTALL_BROWSER=1 \
  -t simpleclaw:browser \
  .

This:

Installs Chromium via Playwright
Installs Xvfb for virtual display
Adds ~300MB to image size
Eliminates 60-90s install on every container start

Without Pre-installed Browser

Browsers install on first use:

# Gateway will auto-install on first browser tool use
docker run ... simpleclaw:latest

Downside: 60-90s delay on first run.

Health Checks

Gateway Health

Add health check to Compose:

services:
  simpleclaw-gateway:
    # ...
    healthcheck:
      test: ["CMD", "node", "dist/index.js", "gateway", "status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

External Health Checks

For platforms requiring external health checks:

Set gateway token:
```
-e SIMPLECLAW_GATEWAY_TOKEN=your-token
```

Bind to LAN:

command:
  - node
  - dist/index.js
  - gateway
  - --bind
  - lan
  - --allow-unconfigured

Query health endpoint:

curl -H "Authorization: Bearer your-token" \
  http://localhost:18789/health

Resource Limits

Memory Limits

services:
  simpleclaw-gateway:
    # ...
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

CPU Limits

services:
  simpleclaw-gateway:
    # ...
    deploy:
      resources:
        limits:
          cpus: '2.0'
        reservations:
          cpus: '0.5'

Node.js Heap Size

services:
  simpleclaw-gateway:
    # ...
    environment:
      NODE_OPTIONS: "--max-old-space-size=2048"

Security

Non-Root User

The image runs as node user (uid 1000):

Prevents privilege escalation
Reduces attack surface
Matches standard Node.js Docker practices

Network Isolation

Bind to loopback for internal-only access:

command:
  - node
  - dist/index.js
  - gateway
  - --bind
  - loopback

Use reverse proxy (nginx, Caddy) for external access.

Secrets Management

Use Docker secrets or external secret managers:

secrets:
  gateway_token:
    external: true
  anthropic_key:
    external: true

services:
  simpleclaw-gateway:
    secrets:
      - gateway_token
      - anthropic_key
    environment:
      SIMPLECLAW_GATEWAY_TOKEN_FILE: /run/secrets/gateway_token
      ANTHROPIC_API_KEY_FILE: /run/secrets/anthropic_key

Persistence

Data Directories

Mount volumes for persistence:

~/.simpleclaw/
├── config.yaml              # Main config (mount)
├── credentials/             # API keys (mount)
├── agents/main/sessions/    # Session logs (mount)
├── agents/main/workspace/   # Agent files (mount)
├── channels/                # Channel state (mount)
└── logs/                    # Gateway logs (optional)

Backup

Back up mounted directories:

# Backup config
tar -czf simpleclaw-backup-$(date +%Y%m%d).tar.gz \
  config/ workspace/

# Restore
tar -xzf simpleclaw-backup-20260303.tar.gz

Updating

Pull New Image

# Pull latest
docker pull simpleclaw:latest

# Restart containers
docker compose down
docker compose up -d

Rebuild Custom Image

# Pull latest source
cd simpleclaw
git pull

# Rebuild image
docker build -t simpleclaw:latest .

# Restart
docker compose down
docker compose up -d

Troubleshooting

Container Won’t Start

Check logs:

docker compose logs simpleclaw-gateway

Common issues:

Port 18789 already in use
Missing environment variables
Volume mount permissions
Invalid config syntax

Permission Errors

Fix volume permissions:

# Set ownership to uid 1000 (node user)
sudo chown -R 1000:1000 config/ workspace/

# Or match your user
sudo chown -R $UID:$UID config/ workspace/

Gateway Not Reachable

Check bind address:

# Inside container
docker exec simpleclaw-gateway ss -ltnp | grep 18789

# Should show 0.0.0.0:18789 for LAN
# Or 127.0.0.1:18789 for loopback

Browser Tools Fail

Install browser dependencies:

# Rebuild with browser support
docker build \
  --build-arg SIMPLECLAW_INSTALL_BROWSER=1 \
  -t simpleclaw:browser \
  .

Production Deployment

systemd Service

Manage Docker Compose via systemd:

# /etc/systemd/system/simpleclaw.service
[Unit]
Description=SimpleClaw Docker Gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/simpleclaw
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl enable simpleclaw
sudo systemctl start simpleclaw

Reverse Proxy

Use nginx or Caddy for TLS:

server {
    listen 443 ssl http2;
    server_name gateway.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Get Started

Core Concepts

Messaging Channels

Features

Platforms

Security

​Overview

​Quick Start

​Using Docker Compose

​Building the Image

​From Repository

​Dockerfile Overview

​Build Arguments

​Running Containers

​Gateway Container

​CLI Container

​Interactive Shell

​Configuration

​Volume Mounts

​Environment Variables

​Network Mode

​Docker Compose Configuration

​Full Example

​Environment File

​Run CLI Commands

​Browser Automation

​With Chromium Pre-installed

​Without Pre-installed Browser

​Health Checks

​Gateway Health

​External Health Checks

​Resource Limits

​Memory Limits

​CPU Limits

​Node.js Heap Size

​Security

​Non-Root User

​Network Isolation

​Secrets Management

​Persistence

​Data Directories

​Backup

​Updating

​Pull New Image

​Rebuild Custom Image

​Troubleshooting

​Container Won’t Start

​Permission Errors

​Gateway Not Reachable

​Browser Tools Fail

​Production Deployment

​systemd Service

​Reverse Proxy

​Related Documentation

Build docs developers (and LLMs) love

Overview

Quick Start

Using Docker Compose

Building the Image

From Repository

Dockerfile Overview

Build Arguments

Running Containers

Gateway Container

CLI Container

Interactive Shell

Configuration

Volume Mounts

Environment Variables

Network Mode

Docker Compose Configuration

Full Example

Environment File

Run CLI Commands

Browser Automation

With Chromium Pre-installed

Without Pre-installed Browser

Health Checks

Gateway Health

External Health Checks

Resource Limits

Memory Limits

CPU Limits

Node.js Heap Size

Security

Non-Root User

Network Isolation

Secrets Management

Persistence

Data Directories

Backup

Updating

Pull New Image

Rebuild Custom Image

Troubleshooting

Container Won’t Start

Permission Errors

Gateway Not Reachable

Browser Tools Fail

Production Deployment

systemd Service

Reverse Proxy

Related Documentation