Docker Deployment

Deploy NullClaw using Docker and docker-compose

NullClaw provides production-ready Docker images optimized for minimal size and security.

Quick Start

1. Pull the image

   docker pull ghcr.io/nullclaw/nullclaw:latest
   
2. Run the gateway

   docker run -p 3000:3000 \
     -e NULLCLAW_API_KEY=your-api-key \
     -v nullclaw-data:/nullclaw-data \
     nullclaw:latest
   
3. Verify it's running

   curl http://localhost:3000/health
   

Building from Source

The Dockerfile uses a multi-stage build optimized for binary size:

# Stage 1: Build with Zig
FROM alpine:3.23 AS builder
RUN apk add --no-cache zig musl-dev
WORKDIR /app
COPY build.zig build.zig.zon ./
COPY src/ src/
RUN zig build -Dtarget="x86_64-linux-musl" -Doptimize=ReleaseSmall

# Stage 2: Runtime
FROM alpine:3.23
RUN apk add --no-cache ca-certificates curl tzdata
COPY --from=builder /app/zig-out/bin/nullclaw /usr/local/bin/nullclaw

EXPOSE 3000
ENTRYPOINT ["nullclaw"]
CMD ["gateway", "--port", "3000", "--host", "::"]

Build locally:

docker build -t nullclaw:latest .

Multi-architecture Builds

The Dockerfile supports both AMD64 and ARM64:

docker buildx build --platform linux/amd64,linux/arm64 -t nullclaw:latest .

The TARGETARCH argument automatically selects the correct Zig target:

• amd64 → x86_64-linux-musl
• arm64 → aarch64-linux-musl

Environment Variables

NULLCLAW_API_KEY · string · required

Your AI provider API key

NULLCLAW_WORKSPACE · string · default: "/nullclaw-data/workspace"

Workspace directory for agent operations

HOME · string · default: "/nullclaw-data"

Home directory for config and data

NULLCLAW_GATEWAY_PORT · string · default: "3000"

Gateway HTTP port

Docker Compose

For production deployments, use docker-compose:

services:
  agent:
    build: .
    image: nullclaw:latest
    profiles: ["agent"]
    stdin_open: true
    tty: true
    env_file:
      - path: .env
        required: false
    volumes:
      - nullclaw-data:/root/.nullclaw
    restart: unless-stopped

  gateway:
    build: .
    image: nullclaw:latest
    profiles: ["gateway"]
    ports:
      - "8080:8080"
    env_file:
      - path: .env
        required: false
    volumes:
      - nullclaw-data:/root/.nullclaw
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  nullclaw-data:

Running Services

Gateway only

docker-compose --profile gateway up -d

Agent only

docker-compose --profile agent up -d

Both

docker-compose --profile gateway --profile agent up -d

Security Modes

NullClaw provides two Docker build targets:

Safe Default (Non-root)

docker build --target release -t nullclaw:safe .

Runs as user 65534:65534 (nobody). This is the default.

Non-root mode cannot install packages or modify system files. Use this for production.

Autonomous Mode (Root)

docker build --target release-root -t nullclaw:root .

Runs as root with full system access. Requires explicit opt-in.

Only use root mode if your agent needs system-level operations. This allows the AI to install packages, modify system files, and spawn processes with elevated privileges.

Configuration

The Docker image includes a default config at /nullclaw-data/.nullclaw/config.json:

{
  "api_key": "",
  "default_provider": "openrouter",
  "default_model": "anthropic/claude-sonnet-4",
  "default_temperature": 0.7,
  "gateway": {
    "port": 3000,
    "host": "::",
    "allow_public_bind": true
  }
}

Override with your own config:

docker run -v $(pwd)/config.json:/nullclaw-data/.nullclaw/config.json \
  nullclaw:latest

Persistent Storage

Use named volumes to persist data across container restarts:

docker volume create nullclaw-data

docker run -v nullclaw-data:/nullclaw-data \
  nullclaw:latest

The volume contains:

• ~/.nullclaw/config.json - Configuration
• ~/.nullclaw/memory.db - SQLite memory backend
• ~/workspace/ - Agent workspace files

Health Checks

The gateway exposes a /health endpoint:

curl http://localhost:3000/health

Response:

{"status": "ok"}

Docker Compose includes automatic health checks:

healthcheck:
  test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
  interval: 30s
  timeout: 5s
  retries: 3

Logging

View container logs:

docker logs -f <container-id>

With docker-compose:

docker-compose logs -f gateway

Resource Limits

NullClaw is designed for minimal resource usage:

• Binary size: < 1 MB (ReleaseSmall)
• Memory footprint: < 5 MB peak RSS
• Zero dependencies beyond libc

Set container limits:

docker run --memory=128m --cpus=0.5 nullclaw:latest

Or in docker-compose:

services:
  gateway:
    image: nullclaw:latest
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 128M
        reservations:
          cpus: '0.25'
          memory: 64M