Running OpenClaw in Docker

Running OpenClaw in Docker lets you containerize your DenchClaw workspace for consistent deployments, easy migration, and better isolation on shared machines or servers. This guide covers everything from a basic docker run to a production-ready docker-compose setup with persistent storage.

If you're deploying to a cloud server, see the VPS deployment guide. For general setup, start with the OpenClaw setup guide.

Prerequisites#

• Docker 24.0+ installed (docker --version)
• Docker Compose v2+ (docker compose version)
• An AI API key (Anthropic, OpenAI, or other supported provider)
• Ports 3100 and 3101 available (or choose alternates)

Option 1: Quick Start With Docker Run#

For the fastest path, pull and run the official image:

docker run -d \
  --name denchclaw \
  -p 3100:3100 \
  -p 3101:3101 \
  -v denchclaw-workspace:/workspace \
  -e ANTHROPIC_API_KEY=your_key_here \
  ghcr.io/denchhq/denchclaw:latest

Then open http://localhost:3100 in your browser.

The -v denchclaw-workspace:/workspace flag creates a named Docker volume for persistence. Your data survives container restarts and updates.

Option 2: Docker Compose (Recommended)#

For anything beyond quick testing, use Docker Compose. It's easier to configure, update, and reason about.

docker-compose.yml#

version: "3.9"
 
services:
  denchclaw:
    image: ghcr.io/denchhq/denchclaw:latest
    container_name: denchclaw
    restart: unless-stopped
    ports:
      - "3100:3100"   # Web UI
      - "3101:3101"   # Gateway API
    volumes:
      - denchclaw-workspace:/workspace
      - ./config:/config:ro      # Optional: mount custom config
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}      # Optional
      - DENCHCLAW_WORKSPACE=/workspace
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s
 
volumes:
  denchclaw-workspace:
    driver: local

.env File#

Create a .env file alongside your docker-compose.yml:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...    # Optional

Never commit your .env file. Add it to .gitignore:

echo ".env" >> .gitignore

Start the Stack#

docker compose up -d

Check logs:

docker compose logs -f denchclaw

Build Your Own Image#

If you're running a modified version of DenchClaw or want full control over the build, here's a Dockerfile:

FROM node:20-alpine AS base
 
# Install system dependencies
RUN apk add --no-cache \
    curl \
    bash \
    git \
    python3 \
    make \
    g++
 
# Set working directory
WORKDIR /app
 
# Install DenchClaw globally
RUN npm install -g denchclaw
 
# Create workspace directory
RUN mkdir -p /workspace
 
# Expose ports
EXPOSE 3100 3101
 
# Set workspace env
ENV DENCHCLAW_WORKSPACE=/workspace
 
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s \
  CMD curl -f http://localhost:3100/health || exit 1
 
# Start
CMD ["openclaw", "gateway", "start", "--bind", "0.0.0.0"]

Build and run:

docker build -t my-denchclaw .
 
docker run -d \
  --name denchclaw \
  -p 3100:3100 \
  -p 3101:3101 \
  -v $(pwd)/workspace:/workspace \
  -e ANTHROPIC_API_KEY=your_key_here \
  my-denchclaw

Volume Mounts: Local Directory vs Named Volume#

Two options for persisting your workspace:

Named Volume (Recommended for Servers)#

volumes:
  denchclaw-workspace:
    driver: local

Docker manages the volume at /var/lib/docker/volumes/denchclaw-workspace/. Survives container removal, easy to backup with docker run --rm -v denchclaw-workspace:/data alpine tar czf - /data.

Bind Mount (Recommended for Development)#

Mount a local directory directly — useful when you want direct file access from the host:

volumes:
  - ./workspace:/workspace

This puts the workspace in ./workspace relative to your docker-compose.yml. You can edit files directly, run duckdb ./workspace/workspace.duckdb from the host, and use your normal backup scripts.

Networking: Expose to LAN or Beyond#

By default, Docker binds to 127.0.0.1 — accessible only from the host. To expose to your local network (so your phone or other machines can connect):

ports:
  - "0.0.0.0:3100:3100"
  - "0.0.0.0:3101:3101"

Or with a specific LAN IP:

ports:
  - "192.168.1.50:3100:3100"

For internet exposure, put Nginx or Caddy in front and terminate TLS there. Don't expose DenchClaw directly on public ports without authentication. See the VPS deployment guide for a full Nginx + TLS setup.

Running Multiple Instances#

Need a dev and prod instance? Use separate projects:

# Production
docker compose -p denchclaw-prod -f docker-compose.prod.yml up -d
 
# Development / staging
docker compose -p denchclaw-dev -f docker-compose.dev.yml up -d

Map them to different ports:

# docker-compose.dev.yml
ports:
  - "3200:3100"
  - "3201:3101"

Updating DenchClaw#

Pull the latest image and recreate the container:

docker compose pull
docker compose up -d

Your workspace data in the named volume is untouched. Only the application binary updates.

Before updating in production, always back up your workspace first:

# Backup from within the container
docker exec denchclaw sh -c \
  'duckdb /workspace/workspace.duckdb "EXPORT DATABASE /tmp/backup (FORMAT PARQUET);"'
 
# Copy backup to host
docker cp denchclaw:/tmp/backup ./backups/$(date +%Y-%m-%d)/

Installing Skills in Docker#

Skills live in the workspace volume, so they persist between restarts. Install them via the DenchClaw chat interface, or exec into the container:

docker exec -it denchclaw sh
 
# Inside the container:
clawhub install gmail
clawhub install github
exit

Or pass skills to install as environment variables and handle them in an entrypoint script if you want a declarative approach.

Environment Variables Reference#

Troubleshooting#

Container starts but UI is unreachable#

Check that the gateway started:

docker logs denchclaw | tail -50

If you see EADDRINUSE, port 3100 or 3101 is already in use on the host. Change the host-side port mapping:

ports:
  - "3110:3100"

DuckDB permission errors#

The workspace volume needs to be writable by the Node.js process inside the container. If using a bind mount with a host directory, set permissions:

chmod 755 ./workspace

Or run the container as the host user:

user: "1000:1000"

Replace 1000:1000 with your actual UID/GID from id -u and id -g.

Container exits immediately#

Run without -d to see startup output:

docker compose up denchclaw

Common causes: missing API key, workspace volume not writable, or node version mismatch in a custom image.

FAQ#

Can I run DenchClaw in Docker on an M-series Mac?
Yes. The official image is multi-arch (amd64 + arm64). Docker Desktop on Apple Silicon runs the arm64 variant natively.

Does Docker Compose persist data when I run docker compose down?
docker compose down removes containers but leaves volumes intact. Only docker compose down -v removes volumes. Your workspace data is safe with a plain down.

Can I run this without root/sudo?
Yes. Docker in rootless mode works for DenchClaw. Alternatively, add your user to the docker group: sudo usermod -aG docker $USER.

How do I access the DenchClaw chat UI from my phone on the same network?
Expose the port to 0.0.0.0 as shown above, then navigate to http://your-host-ip:3100 from your phone's browser. For the full mobile experience, install the companion app instead — see the mobile guide.

What's the container's memory footprint?
DenchClaw typically uses 200–400 MB RAM at idle with a small workspace. Active LLM inference happens via API calls, not locally, so memory usage is relatively stable.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →