Skip to content
RemoteClaw

Hetzner

RemoteClaw on Hetzner (Docker, Production VPS Guide)

Goal

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

If you want “RemoteClaw 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.

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.

What are we doing (simple terms)?

  • Rent a small Linux server (Hetzner VPS)
  • Install Docker (isolated app runtime)
  • Start the RemoteClaw Gateway in Docker
  • Persist ~/.remoteclaw + ~/.remoteclaw/workspace 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 RemoteClaw 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
Create an Ubuntu or Debian VPS in Hetzner. 
Connect as root:


```bash
ssh root@YOUR_VPS_IP
```


This guide assumes the VPS is stateful.
Do not treat it as disposable infrastructure.
 ```bash apt-get update apt-get install -y git curl ca-certificates curl -fsSL https://get.docker.com | sh ``` 
Verify:


```bash
docker --version
docker compose version
```
 ```bash git clone https://github.com/remoteclaw/remoteclaw.git cd remoteclaw ``` 
This guide assumes you will build a custom image to guarantee binary persistence.
 Docker containers are ephemeral. All long-lived state must live on the host. 
```bash
mkdir -p /root/.remoteclaw/workspace


# Set ownership to the container user (uid 1000):
chown -R 1000:1000 /root/.remoteclaw
```
 Create `.env` in the repository root. 
```bash
REMOTECLAW_IMAGE=remoteclaw:latest
REMOTECLAW_GATEWAY_TOKEN=change-me-now
REMOTECLAW_GATEWAY_BIND=lan
REMOTECLAW_GATEWAY_PORT=18789


REMOTECLAW_CONFIG_DIR=/root/.remoteclaw
REMOTECLAW_WORKSPACE_DIR=/root/.remoteclaw/workspace


GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.remoteclaw
```


Generate strong secrets:


```bash
openssl rand -hex 32
```


**Do not commit this file.**
 Create or update `docker-compose.yml`. 
```yaml
services:
  remoteclaw-gateway:
    image: ${REMOTECLAW_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - REMOTECLAW_GATEWAY_BIND=${REMOTECLAW_GATEWAY_BIND}
      - REMOTECLAW_GATEWAY_PORT=${REMOTECLAW_GATEWAY_PORT}
      - REMOTECLAW_GATEWAY_TOKEN=${REMOTECLAW_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:
      - ${REMOTECLAW_CONFIG_DIR}:/home/node/.remoteclaw
      - ${REMOTECLAW_WORKSPACE_DIR}:/home/node/.remoteclaw/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:${REMOTECLAW_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${REMOTECLAW_GATEWAY_BIND}",
        "--port",
        "${REMOTECLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]
```


`--allow-unconfigured` is only for bootstrap convenience, it is not a replacement for a proper gateway configuration. Still set auth (`gateway.auth.token` or password) and use safe bind settings for your deployment.
 Use the shared runtime guide for the common Docker host flow: 
- [Bake required binaries into the image](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Build and launch](/install/docker-vm-runtime#build-and-launch)
- [What persists where](/install/docker-vm-runtime#what-persists-where)
- [Updates](/install/docker-vm-runtime#updates)
 After the shared build and launch steps, 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/`


Paste your gateway token.

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.

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

Next steps