---

name: openclaw-vps-deploy description: > Deploy a custom OpenClaw repo (official or forked) to a Hostinger VPS and make it accessible via the cloud. Use when setting up a new OpenClaw instance on a remote VPS, deploying a custom or forked OpenClaw build to a server, making OpenClaw accessible at a public URL, or setting up OpenClaw as a cloud-hosted service on Hostinger. Handles SSH connection, Node.js install, OpenClaw install (npm package or git clone+build), systemd service, firewall, and auth token generation.

OpenClaw VPS Deploy

Deploy OpenClaw (official or custom fork) to a Hostinger VPS with full cloud access.

Quick Deploy

# Official package (most common)
python3 scripts/deploy.py \
  --ip 187.124.84.25 \
  --key ~/.ssh/id_ed25519 \
  --name "Koda"

# Custom git fork
python3 scripts/deploy.py \
  --ip 187.124.84.25 \
  --key ~/.ssh/id_ed25519 \
  --repo https://github.com/your-org/openclaw \
  --name "Koda" \
  --gw-port 18789

The script auto-reads ANTHROPIC_API_KEY from the local OpenClaw vault (~/.openclaw/secrets.json) or environment. Pass --anthropic to override.

What the Script Does

1. Connects via SSH (key auth — required, password auth often disabled on Hostinger)
2. Installs Node.js 22 via nodesource apt repo
3. Installs OpenClaw — either npm install -g <package> or git clone + pnpm build
4. Writes openclaw.json with correct schema (see critical notes below)
5. Installs systemd service — auto-starts on reboot, restarts on crash
6. Opens UFW ports — SSH (22) + gateway port
7. Saves auth token to local vault as OPENCLAW_VPS_<IP>_TOKEN

SSH Key on WSL2

The user's Windows SSH key is accessible at /mnt/c/Users/<username>/.ssh/id_ed25519 in WSL2. Copy it with correct permissions before use:

cp /mnt/c/Users/charl/.ssh/id_ed25519 /tmp/vps_key
chmod 600 /tmp/vps_key
python3 scripts/deploy.py --ip 1.2.3.4 --key /tmp/vps_key

Getting the Server IP

From the Hostinger tab in the Control dashboard (VPS Servers section), or via API:

mcporter call hostinger-api.VPS_getVirtualMachinesV1 2>&1 | \
  python3 -c "import json,sys; [print(v['id'], v['ipv4'][0]['address'], v['hostname']) for v in json.load(sys.stdin) if v.get('ipv4')]"

Critical Notes (Read Before Manually Deploying)

See references/gotchas.md for full details on every failure mode. Key points:

1. Never use openclaw gateway start as ExecStart — use openclaw gateway --bind lan --auth token --allow-unconfigured
2. Config schema: use agents.list[] not agents.default (causes schema error)
3. Set gateway.mode — required, use "remote" for cloud access
4. Set XDG_RUNTIME_DIR=/run/user/0 in systemd + mkdir -p /run/user/0
5. Add public IP to allowedOrigins — otherwise the UI blocks non-localhost connections
6. Performance: always set OPENCLAW_NO_RESPAWN=1 and NODE_COMPILE_CACHE

Correct openclaw.json Schema

{
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" }
    },
    "list": [
      { "id": "main", "default": true, "name": "Koda" }
    ]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  },
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "mode": "remote",
    "auth": { "mode": "token", "token": "your-token" },
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "http://YOUR.SERVER.IP:18789"
      ]
    }
  }
}

Correct systemd Unit

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root
ExecStart=/usr/bin/openclaw gateway --bind lan --port 18789 --auth token --allow-unconfigured
Restart=always
RestartSec=5
Environment=HOME=/root
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Environment=XDG_RUNTIME_DIR=/run/user/0

[Install]
WantedBy=multi-user.target

Managing a Live Instance

# Status
ssh root@SERVER_IP "systemctl status openclaw"

# Logs (live)
ssh root@SERVER_IP "journalctl -u openclaw -f"

# Restart
ssh root@SERVER_IP "systemctl restart openclaw"

# Update OpenClaw (npm)
ssh root@SERVER_IP "npm install -g openclaw && systemctl restart openclaw"

# Update custom fork (git)
ssh root@SERVER_IP "cd /opt/openclaw && git pull && pnpm install && pnpm build && systemctl restart openclaw"

Accessing the UI

Navigate to http://SERVER_IP:18789. When prompted for an auth token, use the value stored in:

• Local vault: OPENCLAW_VPS_<IP_WITH_UNDERSCORES>_TOKEN
• Or retrieve: python3 -c "import json; v=json.load(open('/home/charl/.openclaw/secrets.json')); [print(k,v[k]) for k in v if 'VPS' in k and 'TOKEN' in k]"

Multi-Agent VPS Setup

One VPS can run multiple isolated agents on separate ports, each with its own Cloudflare URL. No core OpenClaw changes needed — use --config-dir per agent.

See references/multi-agent.md for: port allocation, per-agent systemd services, provisioning script, resource planning, and Cloudflare tunnel integration.

# Each agent = separate gateway on a separate port
openclaw gateway --config-dir /root/agents/koda   --port 18789
openclaw gateway --config-dir /root/agents/alex   --port 18790

Dependencies

• paramiko Python package (auto-installed by deploy.py if missing)
• SSH private key with access to the target VPS
• ANTHROPIC_API_KEY in vault or environment