Skip to main content

​
Clawdbot on Hetzner (Docker, Production VPS Guide)

​
Goal

Run a persistent Clawdbot Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior. If you want “Clawdbot 24/7 for ~$5”, this is the simplest reliable setup. Hetzner pricing changes; pick the smallest Debian/Ubuntu VPS and scale up if you hit OOMs.

​
What are we doing (simple terms)?

  • Rent a small Linux server (Hetzner VPS)
  • Install Docker (isolated app runtime)
  • Start the Clawdbot Gateway in Docker
  • Persist ~/.clawdbot + ~/clawd on the host (survives restarts/rebuilds)
  • Access the Control UI from your laptop via an SSH tunnel
The Gateway can be accessed via:
  • SSH port forwarding from your laptop
  • Direct port exposure if you manage firewalling and tokens yourself
This guide assumes Ubuntu or Debian on Hetzner.
If you are on another Linux VPS, map packages accordingly. For the generic Docker flow, see Docker.

​
Quick path (experienced operators)

  1. Provision Hetzner VPS
  2. Install Docker
  3. Clone Clawdbot repository
  4. Create persistent host directories
  5. Configure .env and docker-compose.yml
  6. Bake required binaries into the image
  7. docker compose up -d
  8. Verify persistence and Gateway access

​
What you need

  • Hetzner VPS with root access
  • SSH access from your laptop
  • Basic comfort with SSH + copy/paste
  • ~20 minutes
  • Docker and Docker Compose
  • Model auth credentials
  • Optional provider credentials
    • WhatsApp QR
    • Telegram bot token
    • Gmail OAuth

​
1) Provision the VPS

Create an Ubuntu or Debian VPS in Hetzner. Connect as root: 
ssh root@YOUR_VPS_IP
This guide assumes the VPS is stateful. Do not treat it as disposable infrastructure.

​
2) Install Docker (on the VPS)

apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh
Verify: 
docker --version
docker compose version

​
3) Clone the Clawdbot repository

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
This guide assumes you will build a custom image to guarantee binary persistence.

​
4) Create persistent host directories

Docker containers are ephemeral. All long-lived state must live on the host. 
mkdir -p /root/.clawdbot
mkdir -p /root/clawd

# Set ownership to the container user (uid 1000):
chown -R 1000:1000 /root/.clawdbot
chown -R 1000:1000 /root/clawd

​
5) Configure environment variables

Create .env in the repository root. 
CLAWDBOT_IMAGE=clawdbot:latest
CLAWDBOT_GATEWAY_TOKEN=change-me-now
CLAWDBOT_GATEWAY_BIND=lan
CLAWDBOT_GATEWAY_PORT=18789
CLAWDBOT_BRIDGE_PORT=18790

CLAWDBOT_CONFIG_DIR=/root/.clawdbot
CLAWDBOT_WORKSPACE_DIR=/root/clawd

GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.clawdbot
Generate strong secrets: 
openssl rand -hex 32
Do not commit this file.

​
6) Docker Compose configuration

Create or update docker-compose.yml. 
services:
  clawdbot-gateway:
    image: ${CLAWDBOT_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - CLAWDBOT_GATEWAY_BIND=${CLAWDBOT_GATEWAY_BIND}
      - CLAWDBOT_GATEWAY_PORT=${CLAWDBOT_GATEWAY_PORT}
      - CLAWDBOT_BRIDGE_PORT=${CLAWDBOT_BRIDGE_PORT}
      - CLAWDBOT_GATEWAY_TOKEN=${CLAWDBOT_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${CLAWDBOT_CONFIG_DIR}:/home/node/.clawdbot
      - ${CLAWDBOT_WORKSPACE_DIR}:/home/node/clawd
    ports:
      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${CLAWDBOT_GATEWAY_PORT}:18789"

      # Optional: only if you run iOS/Android nodes against this VPS.
      # If you expose these publicly, read /gateway/security and firewall accordingly.
      # - "${CLAWDBOT_BRIDGE_PORT}:18790"
      # - "18793:18793"
    command:
      [
        "node",
        "dist/index.js",
        "gateway-daemon",
        "--bind",
        "${CLAWDBOT_GATEWAY_BIND}",
        "--port",
        "${CLAWDBOT_GATEWAY_PORT}"
      ]

​
7) Bake required binaries into the image (critical)

Installing binaries inside a running container is a trap. Anything installed at runtime will be lost on restart. All external binaries required by skills must be installed at image build time. The examples below show three common binaries only:
  • gog for Gmail access
  • goplaces for Google Places
  • wacli for WhatsApp
These are examples, not a complete list. You may install as many binaries as needed using the same pattern. If you add new skills later that depend on additional binaries, you must:
  1. Update the Dockerfile
  2. Rebuild the image
  3. Restart the containers
Example Dockerfile 
FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Example binary 1: Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

# Example binary 2: Google Places CLI
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces

# Example binary 3: WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

# Add more binaries below using the same pattern

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY patches ./patches
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

​
8) Build and launch

docker compose build
docker compose up -d clawdbot-gateway
Verify binaries: 
docker compose exec clawdbot-gateway which gog
docker compose exec clawdbot-gateway which goplaces
docker compose exec clawdbot-gateway which wacli
Expected output: 
/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli

​
9) Verify Gateway

docker compose logs -f clawdbot-gateway
Success: 
[gateway] listening on ws://0.0.0.0:18789
From your laptop: 
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
Open: http://127.0.0.1:18789/ Paste your gateway token.

​
What persists where (source of truth)

Clawdbot runs in Docker, but Docker is not the source of truth. All long-lived state must survive restarts, rebuilds, and reboots.
ComponentLocationPersistence mechanismNotes
Gateway config/home/node/.clawdbot/Host volume mountIncludes clawdbot.json, tokens
Model auth profiles/home/node/.clawdbot/Host volume mountOAuth tokens, API keys
Skill configs/home/node/.clawdbot/skills/Host volume mountSkill-level state
Agent workspace/home/node/clawd/Host volume mountCode and agent artifacts
WhatsApp session/home/node/.clawdbot/Host volume mountPreserves QR login
Gmail keyring/home/node/.clawdbot/Host volume + passwordRequires GOG_KEYRING_PASSWORD
External binaries/usr/local/bin/Docker imageMust be baked at build time
Node runtimeContainer filesystemDocker imageRebuilt every image build
OS packagesContainer filesystemDocker imageDo not install at runtime
Docker containerEphemeralRestartableSafe to destroy