deployment

OpenClaw Deployment

Overview

Deploy OpenClaw to production across Docker, VPS/cloud, Ansible-managed servers, and Nix environments. This skill covers the deployment decision tree, container configuration, cloud provider options, automated provisioning, declarative builds, service management, and distributed node architecture.

Architecture note: The Gateway is the core process in every deployment. It is the single source of truth for configuration, routing, and state. Tools are optionally sandboxed in Docker containers, but the Gateway itself runs as a standalone Node.js process. Always back up ~/.openclaw/ -- it contains all configuration, credentials, and runtime state.

---

Deployment Decision Tree

Select a deployment strategy based on the target environment and operational requirements.

Scenario	Strategy	Tradeoff
Local development	openclaw onboard --install-daemon	Simplest path; no containers or infrastructure to manage
Isolated reproducible environment	Docker	Clean separation between host and runtime; good for sandboxing tools
Always-on remote access	VPS / cloud	Persistent endpoint accessible from any device
Production Debian/Ubuntu with hardening	Ansible	One-command provisioning with 4-layer defense (firewall + VPN + container isolation + systemd hardening)
Declarative reproducible builds	Nix	Pinned versions, deterministic behavior, instant rollback

For local development only, run openclaw onboard --install-daemon and skip the rest of this document. For all other scenarios, continue to the relevant section below.

---

Docker Deployment

Run the Gateway and sandboxed tools inside Docker containers for isolation and reproducibility.

Quick Start

From the OpenClaw repository root:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

The setup script builds the image, creates volumes, and starts the container with port 18789 mapped to the host.

Docker Compose

A docker-compose.yml is available in the repository root for multi-container orchestration. Start with:

docker compose up -d

Container Details

• User: Non-root node user (UID 1000) inside the container. All file operations run as this user.
• Volumes:
  • ~/.openclaw -- Configuration, credentials, and runtime state (mounted into the container).
  • ~/openclaw/workspace -- Sandbox workspace for tool execution.
• Port: 18789 (gateway HTTP API and dashboard).

Permission Fix

If the container reports permission errors on mounted volumes, align host directory ownership to UID 1000:

sudo chown -R 1000:1000 ~/.openclaw

Then restart the container.

Podman Alternative

Podman works as a drop-in replacement. Substitute podman for docker in all commands. Rootless Podman is supported.

For complete Docker configuration options, multi-stage build details, network modes, and Podman-specific adjustments, read ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/docker.md.

---

Ansible Deployment

Automated provisioning for production Debian/Ubuntu servers with comprehensive security hardening.

One-Command Installer

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

This downloads and runs the openclaw-ansible playbook, which handles the full provisioning lifecycle.

Target Systems

• Debian 11+
• Ubuntu 20.04+

Note: macOS Ansible support was discontinued on February 6, 2026. Use a different deployment method for macOS targets.

What the Playbook Installs

1. Tailscale -- Mesh VPN for secure remote access without exposing ports to the public internet.
2. UFW -- Firewall configured to deny all inbound traffic except Tailscale and SSH.
3. Docker + Compose -- Container runtime for tool sandboxing.
4. Node.js 22.x -- Gateway runtime.
5. systemd service -- Managed background service with auto-restart and hardening directives.

4-Layer Defense Model

The Ansible playbook implements defense in depth:

1. Firewall (UFW) -- Blocks all unsolicited inbound traffic.
2. VPN (Tailscale) -- Encrypts all access and authenticates via Tailscale ACLs.
3. Container isolation (Docker) -- Sandboxes tool execution away from the host.
4. systemd hardening -- Restricts the service with ProtectSystem, PrivateTmp, NoNewPrivileges, and capability bounding.

Post-Install Steps

After the playbook completes:

1. Switch to the dedicated OpenClaw user: sudo su - openclaw
2. Run the onboarding wizard: openclaw onboard --install-daemon
3. Configure Tailscale on the host: sudo tailscale up
4. Verify the service: systemctl status openclaw

For the full Ansible playbook reference, variable overrides, inventory configuration, and hardening details, read ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/ansible.md.

---

VPS and Cloud Deployment

Deploy to a remote server for always-on access from any device.

Supported Providers

Provider	Notes
Railway	One-click deploy from GitHub repo
Northflank	Browser-based setup and management
Oracle Cloud	Free tier eligible (ARM instances)
Fly.io	Edge deployment with global regions
Hetzner	Cost-effective European VPS
GCP	Compute Engine or Cloud Run
exe.dev	Developer-focused hosting
AWS	EC2 instances or Lightsail
DigitalOcean	Droplets with simple provisioning

Security Defaults

The Gateway binds to loopback (127.0.0.1) by default. This means it is not accessible from the network without explicit action. Two secure access patterns:

1. SSH tunnel -- Forward the remote port to a local port:

   ssh -L 18789:127.0.0.1:18789 user@server
   

2. Tailscale Serve -- Expose the gateway over the Tailnet:

   tailscale serve --bg 18789
   

Authentication is required when binding the gateway to a broader network interface (e.g., 0.0.0.0). Configure auth tokens in ~/.openclaw/config.yaml under gateway.auth before changing the bind address.

For provider-specific setup guides, pricing notes, and network configuration details, read ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/vps-cloud.md.

---

Nix Deployment

Declarative, reproducible deployment using the Nix package manager and Home Manager.

Home Manager Module

The nix-openclaw module provides a fully declarative OpenClaw installation.

Add to home.nix:

imports = [ nix-openclaw.homeManagerModules.default ];

services.openclaw = {
  enable = true;
};

Then rebuild:

home-manager switch

Deterministic Behavior

Set the environment variable to enforce deterministic mode:

export OPENCLAW_NIX_MODE=1

This disables auto-updates, pins all dependency resolution to the Nix store, and ensures builds are fully reproducible across machines.

Key Environment Variables

Variable	Purpose
OPENCLAW_HOME	Override the home directory (default: ~/.openclaw)
OPENCLAW_STATE_DIR	Override the state/runtime directory
OPENCLAW_CONFIG_PATH	Override the config file path
OPENCLAW_NIX_MODE	Set to 1 for deterministic behavior

Instant Rollback

Roll back to the previous working configuration at any time:

home-manager switch --rollback

This restores the exact prior OpenClaw version and configuration atomically.

For complete Nix flake configuration, module options, overlay setup, and troubleshooting, read ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/nix.md.

---

Service Management

Manage the OpenClaw Gateway as a background service on Linux (systemd) and macOS (launchd).

Daemon Installation

The onboarding wizard handles daemon registration automatically:

openclaw onboard --install-daemon

This auto-detects the platform and writes the appropriate service definition. The gateway starts immediately and is configured to launch on boot.

Linux (systemd)

Control the service with standard systemctl commands:

systemctl start openclaw       # Start the gateway
systemctl stop openclaw        # Stop the gateway
systemctl restart openclaw     # Restart after config changes
systemctl status openclaw      # Check service health
journalctl -u openclaw -f      # Stream live logs

The unit file is installed to ~/.config/systemd/user/openclaw.service (user-level) or /etc/systemd/system/openclaw.service (system-level, used by Ansible).

macOS (launchd)

Control the service with launchctl:

launchctl start com.openclaw.gateway     # Start the gateway
launchctl stop com.openclaw.gateway      # Stop the gateway
launchctl list | grep openclaw           # Check service status

The plist is installed to ~/Library/LaunchAgents/com.openclaw.gateway.plist.

Service Reinstallation After Upgrades

If a version upgrade changes service metadata, reinstall the service definition without re-running the full onboarding wizard:

openclaw gateway install --force

This regenerates the systemd unit or launchd plist with current binary paths and configuration.

Auto-Start on Boot

Both systemd and launchd configurations enable auto-start by default. The gateway launches when the user logs in (user-level service) or when the system boots (system-level service).

For complete service configuration options, log file locations, and platform-specific troubleshooting, read ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/systemd-launchd.md.

---

Distributed Nodes

OpenClaw supports a distributed architecture where the Gateway runs in the cloud and lightweight nodes run on local devices.

Architecture

• Gateway (cloud): Central process handling routing, configuration, and API access. Deploy using any method described above.
• Nodes (local devices): Lightweight agents on Mac, iOS, or Android that provide access to device-specific capabilities -- screen capture, camera, canvas, and local file systems.

Nodes connect outbound to the Gateway over a secure channel. No inbound ports need to be opened on the local device. This allows the Gateway to orchestrate tools that require physical device access without exposing those devices to the network.

---

Reference Files

Load these resources for expanded detail on each deployment method:

• ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/docker.md -- Complete Docker and Docker Compose configuration, multi-stage builds, volume management, network modes, health checks, and Podman compatibility.
• ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/ansible.md -- Full Ansible playbook reference, inventory configuration, variable overrides, 4-layer security model details, and post-provisioning checklist.
• ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/vps-cloud.md -- Provider-specific deployment guides, pricing considerations, network security configuration, SSH tunnel and Tailscale Serve setup, and auth token management.
• ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/nix.md -- Nix flake setup, Home Manager module options, overlay configuration, environment variable reference, deterministic mode details, and rollback procedures.
• ${CLAUDE_PLUGIN_ROOT}/skills/deployment/references/systemd-launchd.md -- systemd unit file and launchd plist specifications, log file locations, journal filtering, auto-restart policies, and platform-specific troubleshooting.