Linux (Direct)

Run the Gateway directly on any Linux distro. Fully supported with systemd service integration.

Linux is the most straightforward deployment target for OpenClaw. The gateway runs as a native Node.js process with systemd integration for automatic startup, restart on failure, and standard log management via journalctl. Any Linux distribution that supports Node.js 22+ works — Ubuntu, Debian, Fedora, Arch, Alpine, you name it. The install path is identical to macOS: run the one-liner installer script or `npm install -g openclaw@latest`, then `openclaw onboard --install-daemon` to set up your provider, channels, and systemd service. The onboarding wizard creates a systemd user service at `~/.config/systemd/user/openclaw-gateway.service` that starts on login and restarts on failure. For always-on servers, convert to a system service and enable lingering so it starts on boot without a login session. Linux gets the full feature set minus the macOS companion app (native Linux companion apps are planned). All channels work reliably, Docker-based agent sandboxing is native and performant (no VM layer like macOS Docker Desktop), and systemd provides enterprise-grade process management. The gateway integrates with standard Linux tooling — systemctl for control, journalctl for logs, and your distro's package manager for Node.js. For VPS deployments, Linux is the default target for all cloud guides (Hetzner, DigitalOcean, GCP, Oracle, Fly.io). The direct Linux install is the foundation that containerized and automated methods (Docker, Ansible, Podman) build on top of. If you're comfortable with Linux system administration, this is the cleanest and most transparent deployment — no abstractions, no containers, just a Node.js process managed by systemd.

Tags: linux, systemd, local

Use Cases

  • Linux desktop users who want a personal AI assistant integrated with their daily workflow
  • Home servers or NAS devices running Linux that are already on 24/7
  • Development machines where the agent assists with coding, testing, and system administration
  • VPS base install before adding Docker sandboxing or reverse proxy layers
  • Old laptops or desktops running Linux repurposed as dedicated AI assistant hardware

Tips

  • For always-on servers, create a system service instead of user service: place the unit file in /etc/systemd/system/ and enable with systemctl enable openclaw
  • Enable loginctl enable-linger for your user if using a user service on a headless server
  • Use journalctl -u openclaw -f (system) or journalctl --user -u openclaw-gateway -f (user) to tail logs
  • Install build-essential (Debian/Ubuntu) or gcc make (Fedora/Arch) before OpenClaw for native module compilation
  • For VPS deployments, use SSH tunneling to access the Control UI: ssh -N -L 18789:127.0.0.1:18789 user@server
  • Add Docker for agent sandboxing even if the gateway runs directly on the host — isolates tool execution without containerizing the gateway
  • Use a Node version manager (nvm, fnm) to keep Node.js updated independently of your distro's package manager

Known Issues & Gotchas

  • The default systemd service is a user service — it only runs when you're logged in. For always-on servers, use a system service or enable loginctl enable-linger
  • Some distros (minimal Debian, Alpine) don't include build-essential — install it before npm install or native modules (sharp) will fail
  • If running as root (not recommended), the gateway may have unrestricted system access — create a dedicated user with minimal privileges
  • Node.js from distro package managers (apt, dnf) may be outdated — use NodeSource repos or a version manager for Node 22+
  • The npm global bin directory may not be in PATH on all distros — check with which openclaw after install
  • Bun is not recommended for the gateway runtime even on Linux — use Node.js for production stability

Alternatives

  • Docker
  • Ansible
  • macOS (Local)
  • Raspberry Pi

Community Feedback

Revived an old 2011 Mac Mini, flashed Ubuntu, installed OpenClaw in 20 minutes. Agents have always been defined by a model and the tools it has access to. When the tool is a fully functional desktop, the world opens up.

— Reddit r/vibecoding

It runs in its own VM that is allowed out to the internet, and has read access to one share on my NAS. Not connected to anything else. This is the correct way to isolate it on Linux.

— Reddit r/sysadmin

The Linux install is dead simple. curl | bash, onboard, done. The systemd service handles restarts. Only complication is if you want Docker sandboxing on top.

— Reddit r/selfhosted

If you aren't running this in a strictly isolated VLAN with zero-trust permissions, you're asking for a breach. The agent has broad system access by design.

— Reddit r/selfhosted

Frequently Asked Questions

Which Linux distro is best for OpenClaw?

Any distro that supports Node.js 22+ works. Ubuntu and Debian are the most tested and have the most community guides. Fedora, Arch, and Alpine also work well. Choose what you're comfortable administering.

How do I make OpenClaw start on boot?

The onboarding wizard creates a systemd user service. For it to start on boot without login, run loginctl enable-linger $(whoami). Alternatively, create a system service in /etc/systemd/system/ for server deployments.

Can I run OpenClaw alongside other services?

Yes. The gateway binds to 127.0.0.1:18789 by default and doesn't conflict with other services. If you need to change the port, use openclaw gateway --port <number> or set OPENCLAW_GATEWAY_PORT.

Is a native Linux companion app available?

Not yet. Native Linux companion apps are planned and contributions are welcome. Currently, the CLI and Control UI in a browser provide full management capabilities.

How do I repair a broken installation?

Run openclaw doctor — it checks for common issues (Node version, PATH, systemd service, permissions) and suggests fixes. For a fresh start, uninstall with npm uninstall -g openclaw and reinstall.

Should I run the gateway as root?

No. Running as root gives the agent unrestricted system access, which is a security risk. Create a dedicated user with minimal privileges, or at minimum run as your regular user. The Ansible deployment method automates this with a dedicated openclaw user.