Neura Market Logo

Run OpenClaw Gateway on Hetzner VPS with Docker

This guide explains how to deploy a persistent OpenClaw Gateway on a Hetzner VPS using Docker, with durable state and baked-in binaries. It is intended for users who want a cost-effective 24/7 gateway solution.

Read this when

  • You want OpenClaw running 24/7 on a cloud VPS (not your laptop)
  • You want a production-grade, always-on Gateway on your own VPS
  • You want full control over persistence, binaries, and restart behavior
  • You are running OpenClaw in Docker on Hetzner or a similar provider

Run a persistent OpenClaw Gateway on a Hetzner VPS with Docker. It keeps durable state, includes baked-in binaries, and handles restarts safely.

Hetzner pricing changes over time. Pick the smallest Debian or Ubuntu VPS that meets your needs, then scale up if you run into OOM errors.

You can reach the Gateway through SSH port forwarding from your laptop, or by exposing ports directly if you handle firewalling and tokens yourself.

Security model reminder:

  • Company-shared agents work fine when everyone is in the same trust boundary and the runtime is used only for business.
  • Keep strict separation: use a dedicated VPS and runtime with dedicated accounts. Do not use personal Apple, Google, browser, or password-manager profiles on that host.
  • If users are adversarial to each other, split them by gateway, host, or OS user.

See Security and VPS hosting.

This guide assumes Ubuntu or Debian on Hetzner. On another Linux VPS, map the 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)
  • About 20 minutes

Quick path

  1. Provision the 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:

ssh root@YOUR_VPS_IP

Treat the VPS as stateful infrastructure, not disposable.

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

Clone the OpenClaw repository

git clone https://github.com/openclaw/openclaw.git
cd 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.

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:

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_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:

openssl rand -hex 32

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

Docker Compose configuration

Create or update docker-compose.yml:

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:

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:

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 that prefer 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 and 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.

Note

Community-maintained. For issues or contributions, see the repository links above.

Next steps