Skip to content

A cloud-init template for OpenClaw on a fresh VPS

A full cloud-init.yaml that turns a stock Ubuntu 22.04 or 24.04 VPS into a running OpenClaw gateway at first boot — NodeSource Node 24, dedicated system user, sealed env file, systemd unit, workspace on a data disk.

Provisioning OpenClaw by hand once is fine. Doing it five times — once for a staging box, once for a production box, once after a panel mistake, twice for new team members — is how you end up with five subtly different installs. The fix is the same as for every other server-class workload: a cloud-init manifest the VPS panel applies at first boot, so the box comes up already correct. Ubuntu’s NoCloud and OVA datasource flow has been standard for years (cloudinit.readthedocs.io), every reputable IaaS panel — Hetzner, Vultr, DigitalOcean, Linode, Scaleway, OVH, Virtuozzo Automator — accepts user-data, and OpenClaw is just an npm-installed Node daemon, exactly the kind of workload cloud-init handles well.

This article gives you a complete cloud-init.yaml that installs OpenClaw on a fresh Ubuntu 22.04 or 24.04 LTS VPS in one boot. The output is a running gateway on 127.0.0.1:18789 (github.com/openclaw/openclaw) with the workspace on a dedicated mount, owned by a dedicated system user, with provider keys in a sealed env file, behind a systemd unit. The only step left is onboarding (which is interactive by design) and the remote-access edge.

What’s happening

Cloud-init runs in three phases — init, config, final — and the manifest below uses four top-level keys that map onto the phases: users, packages, write_files, and runcmd (cloudinit.readthedocs.io — Modules). At the end of runcmd, OpenClaw is installed and the daemon is enabled but not yet onboarded — the manifest deliberately stops before the interactive onboarding step because the pairing token must be entered with a human in front of a terminal.

The manifest does six things in order:

  1. Create the openclaw system user with /var/lib/openclaw as its home and /usr/sbin/nologin as its shell.
  2. Format and mount the secondary disk (if your provider gives you one) at /var/lib/openclaw/.
  3. Install base packages, harden SSH (no passwords), enable unattended security upgrades, set up UFW.
  4. Add the NodeSource APT repo for Node 24, install Node, pin it with apt-mark hold (deb.nodesource.com).
  5. Write the systemd unit and a stub env file at /etc/openclaw/openclaw.env with 0640 root:openclaw.
  6. Install OpenClaw globally via npm and enable the gateway unit so the daemon comes up at every boot.

Onboarding (openclaw onboard) happens after the cloud-init run is done — you SSH in once, run it, and the daemon is ready. After that the VPS comes back from any reboot already running, no human in the loop.

Prerequisites

  • A VPS panel that accepts a user-data field at provision time. Almost every modern panel does — look for “Cloud-init”, “User Data”, “Startup Script”, or similar.
  • An Ubuntu 22.04 or 24.04 LTS image. The manifest is tested on both.
  • Your SSH public key. The manifest pre-authorizes it for the root user; password auth is disabled.
  • Optionally, a secondary disk attached at provision time (preferred — see Sizing storage for OpenClaw memory and skills). If your provider only gives you a single disk, the manifest still works; the workspace just lives on the OS volume.

How to verify

When cloud-init has finished — usually 90 seconds to 3 minutes after first boot, depending on the image — SSH in and check:

cloud-init status --wait
# status: done

The daemon should be enabled and active:

systemctl is-enabled openclaw-gateway.service   # enabled
systemctl is-active openclaw-gateway.service    # active (after onboarding)

Listening sockets should be exactly these (port 18789 is the OpenClaw default — github.com/openclaw/openclaw):

ss -lntp | grep -E ':(22|18789)\b'
# 0.0.0.0:22       sshd
# 127.0.0.1:18789  node (openclaw gateway) — only after onboarding completes

If 18789 is not listening yet, that is expected — the unit started but the daemon has no config until you run openclaw onboard.

The fix

The manifest

Save the following as cloud-init.yaml and paste it into your panel’s user-data field at provision time. Substitute the SSH key on line 9, the API key placeholder, and the data-disk device if your provider gives you one with a different name (Hetzner: /dev/sdb, DigitalOcean: /dev/sda with the OS on /dev/vda, Vultr: /dev/vdb).

#cloud-config
# OpenClaw IaaS — first-boot manifest for Ubuntu 22.04 / 24.04 LTS
# After cloud-init runs, SSH in and: sudo -u openclaw HOME=/var/lib/openclaw /usr/bin/openclaw onboard

hostname: openclaw-prod
manage_etc_hosts: true
preserve_hostname: false

users:
  - name: root
    ssh_authorized_keys:
      - ssh-ed25519 AAAAC3Nz...REPLACE_ME you@example.com
  - name: openclaw
    system: true
    shell: /usr/sbin/nologin
    home: /var/lib/openclaw
    create_home: false

package_update: true
package_upgrade: true
packages:
  - curl
  - ca-certificates
  - gnupg
  - build-essential
  - ufw
  - fail2ban
  - unattended-upgrades
  - chrony
  - jq
  - iproute2
  - lsof
  - parted

# Workspace disk — only if your provider gives you a second disk.
# If not, comment this whole section out; the workspace will live on /.
disk_setup:
  /dev/vdb:
    table_type: gpt
    layout: true
    overwrite: false

fs_setup:
  - label: openclaw-data
    filesystem: ext4
    device: /dev/vdb
    partition: auto

mounts:
  - [ "LABEL=openclaw-data", "/var/lib/openclaw", "ext4", "defaults,noatime", "0", "2" ]

write_files:
  - path: /etc/ssh/sshd_config.d/99-openclaw.conf
    permissions: '0644'
    content: |
      PasswordAuthentication no
      PermitRootLogin prohibit-password
      KbdInteractiveAuthentication no

  - path: /etc/apt/apt.conf.d/20auto-upgrades
    permissions: '0644'
    content: |
      APT::Periodic::Update-Package-Lists "1";
      APT::Periodic::Unattended-Upgrade "1";
      APT::Periodic::AutocleanInterval "7";

  - path: /etc/fail2ban/jail.d/sshd.local
    permissions: '0644'
    content: |
      [sshd]
      enabled = true
      port = ssh
      backend = systemd
      maxretry = 4
      findtime = 10m
      bantime = 1h

  - path: /etc/openclaw/openclaw.env
    permissions: '0640'
    owner: 'root:openclaw'
    defer: true
    content: |
      # Replace ANTHROPIC_API_KEY with your provider key before starting the unit
      ANTHROPIC_API_KEY=sk-ant-REPLACE_ME
      OPENCLAW_HOME=/var/lib/openclaw
      OPENCLAW_GATEWAY_BIND=127.0.0.1
      OPENCLAW_GATEWAY_PORT=18789

  - path: /etc/systemd/system/openclaw-gateway.service
    permissions: '0644'
    content: |
      [Unit]
      Description=OpenClaw gateway daemon
      After=network-online.target
      Wants=network-online.target

      [Service]
      Type=simple
      User=openclaw
      Group=openclaw
      WorkingDirectory=/var/lib/openclaw
      EnvironmentFile=/etc/openclaw/openclaw.env
      ExecStart=/usr/bin/openclaw gateway --port 18789
      Restart=on-failure
      RestartSec=5
      StandardOutput=journal
      StandardError=journal

      NoNewPrivileges=true
      PrivateTmp=true
      ProtectSystem=strict
      ReadWritePaths=/var/lib/openclaw
      ProtectHome=true
      ProtectKernelTunables=true
      ProtectKernelModules=true
      ProtectControlGroups=true
      RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
      RestrictNamespaces=true
      LockPersonality=true
      SystemCallArchitectures=native

      LimitNOFILE=65536
      MemoryMax=3G

      [Install]
      WantedBy=multi-user.target

runcmd:
  # Mountpoint exists before mount unit fires
  - [ install, -d, -m, '0750', -o, openclaw, -g, openclaw, /var/lib/openclaw ]

  # NTP
  - [ systemctl, enable, --now, chrony ]

  # UFW: SSH only — remote access goes through Tailscale / Cloudflare Tunnel
  - [ ufw, --force, reset ]
  - [ ufw, default, deny, incoming ]
  - [ ufw, default, allow, outgoing ]
  - [ ufw, allow, '22/tcp' ]
  - [ ufw, --force, enable ]

  # fail2ban
  - [ systemctl, enable, --now, fail2ban ]

  # NodeSource Node 24
  - bash -c "curl -fsSL https://deb.nodesource.com/setup_24.x | bash -"
  - [ apt-get, install, -y, nodejs ]
  - [ apt-mark, hold, nodejs ]

  # OpenClaw global install — npm puts the binary at /usr/bin/openclaw
  - [ npm, install, -g, openclaw@latest ]

  # Re-apply ownership in case the mount wiped it
  - [ chown, -R, 'openclaw:openclaw', /var/lib/openclaw ]
  - [ chmod, '0750', /var/lib/openclaw ]

  # SSH hardening file is in place; restart sshd
  - [ systemctl, restart, ssh ]

  # Enable the gateway unit. It will fail until onboarding writes openclaw.json;
  # systemd will keep retrying every 5 s. That is fine for now.
  - [ systemctl, daemon-reload ]
  - [ systemctl, enable, --now, openclaw-gateway.service ]

  # Touch a flag file so you can tell at a glance that cloud-init finished
  - [ touch, /var/lib/openclaw/.cloud-init-done ]

final_message: "OpenClaw provisioned. SSH in, edit /etc/openclaw/openclaw.env, then: sudo -u openclaw HOME=/var/lib/openclaw /usr/bin/openclaw onboard"

Single-disk variant

If your VPS only has one disk (most cheap-tier panels), comment out the disk_setup, fs_setup, and mounts blocks. The workspace will live at /var/lib/openclaw/ on the OS volume. Everything else works unchanged — just remember the entire box is now a single failure domain. See Sizing storage for OpenClaw memory and skills for why a separate workspace volume earns its keep.

Sealed env file from a secret store

The manifest above ships a stub env file with a placeholder key — that is deliberate, because a real key has no business sitting in a panel’s user-data field where the panel logs it. The patterns that work:

  1. Manual edit on first SSH. Pragmatic for one-off boxes. SSH in once, edit /etc/openclaw/openclaw.env, systemctl restart openclaw-gateway.service.
  2. Pull from a secret store at boot. Add a runcmd line that pulls from HashiCorp Vault, AWS Secrets Manager, Doppler, or 1Password — the canonical pattern is documented in the secrets-engine docs of each tool (developer.hashicorp.com — Vault Agent).
  3. Vendor the env file at provision time via SSM or User Data extras. Works on AWS and some panels; check what your provider supports.

For most personal/team OpenClaw deployments option (1) is fine — the env file is touched once and rotated only when the LLM provider key rotates.

After cloud-init finishes

# Verify cloud-init exit
cloud-init status --wait

# Replace the placeholder API key
sudo $EDITOR /etc/openclaw/openclaw.env

# Onboard — this is interactive, hence not in cloud-init
sudo -u openclaw HOME=/var/lib/openclaw /usr/bin/openclaw onboard

# Restart the daemon so it picks up the new config
sudo systemctl restart openclaw-gateway.service
sudo systemctl status openclaw-gateway.service --no-pager

Then bolt on the remote-access edge — Tailscale, Cloudflare Tunnel, or Caddy. See DNS, TLS, and secure remote access to OpenClaw.

What this manifest deliberately does not do

It does not install the channel SDKs — Telegram, Slack, Discord, etc. The OpenClaw npm package bundles them, and the agent loads them when you configure channels in openclaw.json. There is nothing to install ahead of time.

It does not install a reverse proxy. The right edge is workload-dependent — Tailscale for personal-use, Cloudflare Tunnel when you want a public hostname, Caddy when you control the public IP. Pick one and follow DNS, TLS, and secure remote access to OpenClaw.

It does not configure backup. The workspace is at /var/lib/openclaw/ and /etc/openclaw/openclaw.env holds the keys, but the backup target — restic to S3, ZFS snapshots, the panel’s own snapshot feature — is a choice that depends on what storage you have. See Snapshot and backup strategy for cloud-hosted OpenClaw.

It does not run openclaw onboard. Onboarding asks interactive questions and writes the auth token to the workspace — putting it inside cloud-init either fails (no TTY) or leaks the token into cloud-init logs. The friction of one manual command is the right cost.

Troubleshooting

cloud-init status says error. Read /var/log/cloud-init.log and /var/log/cloud-init-output.log. Most failures are either a bad SSH key in users, a wrong device name in disk_setup, or a transient APT mirror error during package install.

The gateway unit is activating (auto-restart) forever. That is the daemon failing because openclaw.json does not exist yet. Run openclaw onboard once and it will start cleanly.

disk_setup did not partition the second disk. Two common causes: wrong device name (verify with lsblk) or a leftover partition table from a previous boot. wipefs -a /dev/vdb then re-run cloud-init via cloud-init clean && reboot for a hard reset (cloudinit.readthedocs.io — Manual clean).

Node hold did not take. Confirm with apt-mark showhold | grep nodejs. If it is missing, run apt-mark hold nodejs manually. Without the hold an unattended-upgrade major-version bump can take the daemon down.

Sources


Last verified on OpenClaw current.

Have us deploy this for you.