openclaw-openclaw/docs/vps.md at main

mirror of https://github.com/openclaw/openclaw.git synced 2026-07-06 19:32:58 +08:00

Files

Peter Steinberger f7d7148cf0 docs: rewrite published docs grounded in current source (#100142 )

Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green.

Closes #100141

2026-07-05 00:32:47 -04:00

5.6 KiB

Raw Permalink Blame History

summary, read_when, title, sidebarTitle

summary

read_when

title

sidebarTitle

Run OpenClaw on a Linux server or cloud VPS — provider picker, architecture, and tuning

You want to run the Gateway on a Linux server or cloud VPS

You need a quick map of hosting guides

You want generic Linux server tuning for OpenClaw

Linux server

Linux Server

Run the OpenClaw Gateway on any Linux server or cloud VPS. This page helps you pick a provider, explains how cloud deployments work, and covers generic Linux tuning that applies everywhere.

Pick a provider

Linux VM Simple paid VPS VM with HTTPS proxy Fly Machines Compute Engine Docker on Hetzner VPS VPS with one-click setup One-click, browser setup Always Free ARM tier One-click, browser setup ARM self-hosted

AWS (EC2 / Lightsail / free tier) also works well. A community video walkthrough is available at x.com/techfrenAJ/status/2014934471095812547 (community resource -- may become unavailable).

How cloud setups work

The Gateway runs on the VPS and owns state + workspace.
You connect from your laptop or phone via the Control UI or Tailscale/SSH.
Treat the VPS as the source of truth and back up the state + workspace regularly.
Secure default: keep the Gateway on loopback and access it via SSH tunnel or Tailscale Serve. If you bind to lan or tailnet, the Gateway requires a shared secret (gateway.auth.token or gateway.auth.password) unless auth is delegated to a trusted proxy.

Related pages: Gateway remote access, Platforms hub.

Harden admin access first

Before you install OpenClaw on a public VPS, decide how you want to administer the box itself.

For Tailnet-only admin access: install Tailscale first, join the VPS to your tailnet, verify a second SSH session over the Tailscale IP or MagicDNS name, then restrict public SSH.
Without Tailscale: apply the equivalent hardening for your SSH path before exposing more services.
This is separate from Gateway access. You can still keep OpenClaw bound to loopback and use an SSH tunnel or Tailscale Serve for the dashboard.

Tailscale-specific Gateway options live in Tailscale.

Shared company agent on a VPS

Running a single agent for a team is a valid setup when every user is in the same trust boundary and the agent is business-only.

Keep it on a dedicated runtime (VPS/VM/container + dedicated OS user/accounts).
Do not sign that runtime into personal Apple/Google accounts or personal browser/password-manager profiles.
If users are adversarial to each other, split by gateway/host/OS user.

Security model details: Security.

Using nodes with a VPS

You can keep the Gateway in the cloud and pair nodes on your local devices (Mac/iOS/Android/headless). Nodes provide local screen/camera/canvas and system.run capabilities while the Gateway stays in the cloud.

Docs: Nodes, Nodes CLI.

Startup tuning for small VMs and ARM hosts

If CLI commands feel slow on low-power VMs (or ARM hosts), enable Node's module compile cache:

grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF'
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc

NODE_COMPILE_CACHE improves repeated command startup times; the first run warms the cache.
OPENCLAW_NO_RESPAWN=1 keeps routine Gateway restarts in-process, which avoids extra process handoffs and keeps PID tracking simple on small hosts.
For Raspberry Pi specifics, see Raspberry Pi.

systemd tuning checklist (optional)

For VM hosts using systemd, consider:

Service env for a stable startup path: OPENCLAW_NO_RESPAWN=1 and NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Explicit restart behavior: Restart=always, RestartSec=2, TimeoutStartSec=90
SSD-backed disks for state/cache paths to reduce random-I/O cold-start penalties.

The standard openclaw onboard --install-daemon path installs a systemd user unit; edit it with:

systemctl --user edit openclaw-gateway.service

[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90

If you deliberately installed a system unit instead, edit it via sudo systemctl edit openclaw-gateway.service.

How Restart= policies help automated recovery: systemd can automate service recovery.

For Linux OOM behavior, child process victim selection, and exit 137 diagnostics, see Linux memory pressure and OOM kills.

5.6 KiB Raw Permalink Blame History