Running Multiple OpenClaw Instances: Multi-Tenant Docker Guide

Running one OpenClaw instance is straightforward. Running 20 or 50 on the same server — each for a different user, fully isolated, with HTTPS and its own subdomain — requires planning. This guide covers the architecture, resource management, and operational practices for multi-tenant OpenClaw deployments. This is the same approach that ClawTank uses to host hundreds of OpenClaw instances.

Architecture Overview

Each user gets:

• A dedicated Docker container running the openclaw-stack image
• A unique port from a managed pool (e.g., 18800-18899)
• A subdomain (e.g., alice.yourdomain.com) routed through Caddy
• Automatic TLS via Let's Encrypt
• Isolated filesystem, network, and resources

User A ──→ alice.yourdomain.com ──→ Caddy ──→ localhost:18800 ──→ Container A
User B ──→ bob.yourdomain.com   ──→ Caddy ──→ localhost:18801 ──→ Container B
User C ──→ carol.yourdomain.com ──→ Caddy ──→ localhost:18802 ──→ Container C

Docker Container Setup

Creating a User Container

docker run -d \
  --name openclaw-alice \
  --restart unless-stopped \
  -p 18800:3001 \
  -m 512m \
  --cpus=1 \
  -v openclaw-alice-data:/app/data \
  -e OPENCLAW_GATEWAY_TOKEN=alice-unique-token \
  -e ANTHROPIC_API_KEY=sk-ant-alice-key \
  openclaw/openclaw:latest

Key flags:

• -m 512m — hard memory limit of 512MB
• --cpus=1 — limit to 1 CPU core
• Unique volume for data persistence
• Unique gateway token (prevents token regeneration on restart)^[1]
• Each user provides their own API key

Docker Compose for Multiple Users

For managing several containers declaratively:

version: '3.8'

services:
  openclaw-alice:
    image: openclaw/openclaw:latest
    container_name: openclaw-alice
    restart: unless-stopped
    ports:
      - "18800:3001"
    volumes:
      - alice_data:/app/data
    environment:
      - OPENCLAW_GATEWAY_TOKEN=alice-unique-token-here
      - ANTHROPIC_API_KEY=${ALICE_API_KEY}
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.0'
        reservations:
          memory: 256M
          cpus: '0.25'

  openclaw-bob:
    image: openclaw/openclaw:latest
    container_name: openclaw-bob
    restart: unless-stopped
    ports:
      - "18801:3001"
    volumes:
      - bob_data:/app/data
    environment:
      - OPENCLAW_GATEWAY_TOKEN=bob-unique-token-here
      - ANTHROPIC_API_KEY=${BOB_API_KEY}
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.0'
        reservations:
          memory: 256M
          cpus: '0.25'

volumes:
  alice_data:
  bob_data:

In practice, you will want to generate this configuration programmatically rather than editing YAML by hand for each user.

Port Allocation Strategy

Assign a port range and track allocations in a database or config file:

When provisioning a new user:

1. Query the database for the next available port in the range
2. Create the container with that port mapping
3. Store the user-port mapping
4. Update the Caddy configuration

A systematic approach prevents port conflicts and makes it easy to find which container belongs to which user.

Resource Limits and Memory Usage

How Much Memory Does OpenClaw Need?

A single OpenClaw container at idle uses approximately 200-300MB of RAM. Under active use (processing messages, running skills), it can spike to 400-600MB. The gateway process itself accounts for most of the baseline usage.^[2]

Recommended limits per container:

Server Sizing

For a VPS hosting multiple instances:

These estimates assume standard workloads. Heavy users running browser automation or Ralph Loop will require more headroom.

Overcommitting Resources

Not all users are active simultaneously. You can safely allocate more total memory than physically available, as long as you set hard limits per container. Docker's memory limit prevents any single container from consuming all available RAM.

A reasonable overcommit ratio is 1.5x — if you have 16GB of RAM, you can allocate up to 24GB total across containers. Monitor swap usage; if the server is swapping frequently, reduce the ratio.

Caddy Reverse Proxy with Auto-TLS

Caddy is ideal for multi-tenant setups because it handles TLS certificates automatically per subdomain^[3].

Caddyfile Structure

alice.yourdomain.com {
    reverse_proxy localhost:18800
}

bob.yourdomain.com {
    reverse_proxy localhost:18801
}

carol.yourdomain.com {
    reverse_proxy localhost:18802
}

Regenerating the Caddyfile

When users are added or removed, regenerate the entire Caddyfile from your database and reload:

# Generate Caddyfile from database
./generate-caddyfile.sh > /etc/caddy/Caddyfile

# Reload with adapter flag (important!)
caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile

Always use the --adapter caddyfile flag when reloading. Without it, Caddy may fail silently.

DNS Setup

Create a wildcard DNS A record pointing to your server:

Type: A
Name: *.yourdomain.com
Value: YOUR_SERVER_IP
TTL: 300

Important for Cloudflare users: Cloudflare's free plan does not support proxied wildcard DNS. Set the record to DNS only (grey cloud icon), not Proxied. Caddy will handle TLS directly via Let's Encrypt HTTP-01 challenges.

Trusted Proxies

Every OpenClaw container needs to trust the Caddy proxy. Include this in the container setup:

docker exec openclaw-alice openclaw config set gateway.trustedProxies '["127.0.0.1"]'

Or set it via environment variable in the docker-compose.yml.

Security Isolation

What Docker Provides

• Filesystem isolation — containers cannot access each other's files
• Process isolation — one container cannot see or kill processes in another
• Network isolation — containers only communicate through explicitly mapped ports
• User namespace mapping — root inside the container maps to an unprivileged user on the host

Additional Hardening

docker run -d \
  --name openclaw-alice \
  --read-only \
  --cap-drop=ALL \
  --cap-add=NET_BIND_SERVICE \
  --security-opt no-new-privileges \
  -v openclaw-alice-data:/app/data \
  ...

• --read-only — filesystem is read-only except for the mounted data volume
• --cap-drop=ALL — remove all Linux capabilities
• --no-new-privileges — prevent privilege escalation inside the container

API Key Isolation

Each user provides their own AI provider API key. Never share a single API key across users — it creates billing ambiguity and a single point of failure. If one user's key is revoked or rate-limited, only their instance is affected.

Monitoring

Container Health Checks

Add health checks to detect unresponsive containers:

docker inspect --format='{{.State.Health.Status}}' openclaw-alice

Resource Usage

Monitor memory and CPU per container:

docker stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}\t{{.CPUPerc}}"

Run this on a cron job and alert if any container exceeds 90% of its memory limit.

Log Aggregation

Collect logs from all containers for debugging:

docker logs --tail 50 openclaw-alice

For a production setup, forward container logs to a centralized system (Loki, ELK, or even a simple log rotation setup).

Scaling Considerations

Vertical Scaling

The simplest approach: upgrade to a bigger VPS. Move from 4GB to 16GB RAM and you go from 10 to 50 users without changing anything else.

Horizontal Scaling

When a single server is not enough:

1. Run a load balancer (or DNS-based routing) in front of multiple servers
2. Each server runs a subset of user containers
3. A central database tracks which user is on which server
4. Caddy runs on each server, handling TLS for its own users

Container Orchestration

For 100+ users, consider Kubernetes or Docker Swarm for automated scheduling, scaling, and failover. The tradeoff is significant operational complexity.

For most deployments under 100 users, a single well-provisioned server with the approach described in this guide is simpler and more than sufficient.

Or Let ClawTank Handle It

Everything described in this guide — container provisioning, port allocation, Caddy configuration, TLS, resource limits, monitoring — is exactly what ClawTank automates. Each user gets an isolated container with auto-TLS, resource guarantees, and a management dashboard. If you want to offer OpenClaw hosting to others without building the infrastructure yourself, ClawTank is the ready-made platform.

References

1. OpenClaw Docker Setup Guide
2. OpenClaw System Requirements
3. Caddy — Automatic HTTPS
4. Docker Resource Constraints Documentation
5. Docker Security Best Practices