OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Hosting

Hetzner

Run a persistent OpenClaw Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior.

Hetzner pricing changes; pick the smallest Debian/Ubuntu VPS that fits and scale up if you hit OOMs.

The Gateway can be accessed via SSH port forwarding from your laptop, or via direct port exposure if you manage firewalling and tokens yourself.

Security model reminder:

  • Company-shared agents are fine when everyone is in the same trust boundary and the runtime is business-only.
  • Keep strict separation: dedicated VPS/runtime + dedicated accounts; no personal Apple/Google/browser/password-manager profiles on that host.
  • If users are adversarial to each other, split by gateway/host/OS user.

See Security and VPS hosting.

This guide assumes Ubuntu or Debian on Hetzner. On another Linux VPS, map packages accordingly. For the generic Docker flow, see Docker.

What you need

  • Hetzner VPS with root access
  • SSH access from your laptop
  • Docker and Docker Compose
  • Model auth credentials
  • Optional provider credentials (WhatsApp QR, Telegram bot token, Gmail OAuth)
  • ~20 minutes

Quick path

  1. Provision Hetzner VPS
  2. Install Docker
  3. Clone the OpenClaw 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

  • Provision the VPS

    Create an Ubuntu or Debian VPS in Hetzner, then connect as root:

    bash
    ssh root@YOUR_VPS_IP

    Treat the VPS as stateful, not disposable infrastructure.

  • Install Docker (on the VPS)

    bash
    apt-get updateapt-get install -y git curl ca-certificatescurl -fsSL https://get.docker.com | sh

    Verify:

    bash
    docker --versiondocker compose version

  • Clone the OpenClaw repository

    bash
    git clone https://github.com/openclaw/openclaw.gitcd openclaw

    This guide builds a custom image so any binaries you bake in survive restarts.

  • Create persistent host directories

    Docker containers are ephemeral; all long-lived state must live on the host.

    bash
    mkdir -p /root/.openclaw/workspace # Set ownership to the container user (uid 1000):chown -R 1000:1000 /root/.openclaw

  • Configure environment variables

    Create .env in the repository root:

    bash
    OPENCLAW_IMAGE=openclaw:latestOPENCLAW_GATEWAY_TOKEN=OPENCLAW_GATEWAY_BIND=lanOPENCLAW_GATEWAY_PORT=18789 OPENCLAW_CONFIG_DIR=/root/.openclawOPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace GOG_KEYRING_PASSWORD=XDG_CONFIG_HOME=/home/node/.openclaw

    Set OPENCLAW_GATEWAY_TOKEN to manage the stable gateway token through .env; otherwise configure gateway.auth.token before relying on clients across restarts. If neither is set, OpenClaw uses a runtime-only token for that startup. Generate a keyring password for GOG_KEYRING_PASSWORD:

    bash
    openssl rand -hex 32

    Do not commit this file. It holds container/runtime env such as OPENCLAW_GATEWAY_TOKEN. Stored provider OAuth/API-key auth lives in the mounted ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

  • Docker Compose configuration

    Create or update docker-compose.yml:

    yaml
    services:  openclaw-gateway:    image: ${OPENCLAW_IMAGE}    build: .    restart: unless-stopped    env_file:      - .env    environment:      - HOME=/home/node      - NODE_ENV=production      - TERM=xterm-256color      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_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:      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace    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:${OPENCLAW_GATEWAY_PORT}:18789"    command:      [        "node",        "dist/index.js",        "gateway",        "--bind",        "${OPENCLAW_GATEWAY_BIND}",        "--port",        "${OPENCLAW_GATEWAY_PORT}",        "--allow-unconfigured",      ]

    --allow-unconfigured is only for bootstrap convenience, not a substitute for real gateway configuration. Still set auth (gateway.auth.token or password) and a safe bind mode for your deployment.

  • Shared Docker VM runtime steps

    Follow the shared runtime guide for the common Docker host flow:

  • Hetzner-specific access

    After the shared build and launch steps, open the tunnel.

    Prerequisite: ensure your VPS sshd config allows TCP forwarding. If you hardened your SSH config, check /etc/ssh/sshd_config and set:

    text
    AllowTcpForwarding local

    local allows ssh -L local forwards from your laptop while blocking remote forwards from the server. Setting it to no fails the tunnel with: channel 3: open failed: administratively prohibited: open failed

    After confirming TCP forwarding is enabled, restart the SSH service (systemctl restart ssh) and run the tunnel from your laptop:

    bash
    ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

    Open http://127.0.0.1:18789/ and paste the configured shared secret. This guide uses the gateway token by default; use your configured password instead if you switched to password auth.

    • The shared persistence map lives in Docker VM Runtime.

    Infrastructure as Code (Terraform)

    For teams preferring infrastructure-as-code workflows, a community-maintained Terraform setup provides:

    • Modular Terraform configuration with remote state management
    • Automated provisioning via cloud-init
    • Deployment scripts (bootstrap, deploy, backup/restore)
    • Security hardening (firewall, UFW, SSH-only access)
    • SSH tunnel configuration for gateway access

    Repositories:

    This approach complements the Docker setup above with reproducible deployments, version-controlled infrastructure, and automated disaster recovery.

    Next steps

    Was this useful?
    On this page

    On this page