# How to Deploy OpenClaw Headless on Raspberry Pi A headless OpenClaw deployment runs the AI agent on a Raspberry Pi without a monitor or keyboard, managed entirely via SSH and systemd, with Docker providing container-level security isolation. This guide walks through flashing Pi OS Lite, installing OpenClaw, configuring systemd for auto-restart, hardening with Docker, and locking down the network with UFW. Source: https://fast.io/resources/openclaw-raspberry-pi-headless-deployment/ Last reviewed: 2026-03-21 ## Why Run OpenClaw Headless on a Raspberry Pi Running OpenClaw on a Raspberry Pi gives you a dedicated, always-on AI agent for about $4 to published pricing in electricity. A Pi 5 draws roughly 6W under typical load, which is a fraction of what even the cheapest cloud VM costs monthly. The headless approach strips away the desktop environment, freeing about 600 MB of RAM for OpenClaw's orchestration work. The Pi doesn't run LLMs locally. It acts as an orchestration layer that manages tool calls, channel integrations (Telegram, Discord, Slack), and workflow automation while delegating reasoning to cloud APIs like Anthropic, OpenAI, or Google. This separation means a $80 Pi 5 with 8 GB RAM handles the coordination work comfortably, and your AI budget goes toward API calls rather than hardware. Most headless Pi guides stop at "install the software and SSH in." This guide goes further: systemd for process management, Docker for container isolation, UFW for firewall rules, and gateway token rotation for credential hygiene. If your agent has access to tools that can execute code, send messages, or modify files, these layers matter. ## What to check before scaling openclaw raspberry pi headless Start with the right hardware. A Raspberry Pi 5 with 8 GB RAM is the recommended baseline. The Pi 4 with 4 GB works but struggles with multiple concurrent tool calls. Avoid the 2 GB variant entirely. SD cards create a bottleneck for OpenClaw's frequent small reads and writes to its SQLite database. The official Raspberry Pi M.2 HAT with a budget NVMe drive eliminates this problem and costs under $30. Use the official 27W USB-C power supply. Third-party chargers frequently trigger under-voltage warnings when an SSD and active cooler draw power simultaneously. The official Pi 5 case with integrated fan costs about $10 and prevents thermal throttling during sustained agent workloads. ### Flash Raspberry Pi OS Lite Open the Raspberry Pi Imager and select Raspberry Pi OS Lite (64-bit). You need the 64-bit version, as 32-bit is not supported. Before flashing, configure these settings in the Imager: - Hostname: `gateway-host` (or your preferred name) - Enable SSH with password authentication - Set your username and password - Configure WiFi credentials if not using Ethernet Flash the image to your NVMe or SD card, insert it into the Pi, and power on. Give it a minute to boot, then connect: ``` ssh youruser@gateway-host ``` Once connected, update the system and install dependencies: ``` sudo apt update && sudo apt upgrade -y sudo apt install -y git curl build-essential ``` ### Optimize for Headless Use Reduce GPU memory allocation since there's no display attached, and disable Bluetooth if you won't use it: ``` echo 'gpu_mem=16' | sudo tee -a /boot/config.txt sudo systemctl disable bluetooth ``` If you're running a 2 GB or 4 GB Pi, configure swap space. This is critical for avoiding out-of-memory kills: ``` sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf sudo sysctl -p ``` ## Install OpenClaw and Configure the Gateway OpenClaw requires Node.js 22 or later. Install it from the NodeSource repository: ``` curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs node --version ``` Then install OpenClaw itself: ``` curl -fsSL https://openclaw.ai/install.sh | bash ``` Run the onboarding wizard with the daemon flag to set up headless operation: ``` openclaw onboard --install-daemon ``` This registers the Gateway as a systemd service and prompts you for API keys. Use API key authentication rather than OAuth for headless devices, since there's no browser available for the OAuth redirect flow. Verify the gateway is running: ``` openclaw gateway status ``` The Gateway listens on port 18789 by default. On a headless Pi, you won't access the dashboard directly. Instead, create an SSH tunnel from your laptop: ``` ssh -N -L 18789:127.0.0.1:18789 youruser@gateway-host ``` Then open `http://localhost:18789` in your local browser to access the OpenClaw dashboard remotely. ### Speed Up CLI Response Time OpenClaw's Node.js CLI benefits from compile caching. Add these to your shell profile: ``` export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache mkdir -p /var/tmp/openclaw-compile-cache export OPENCLAW_NO_RESPAWN=1 ``` This reduces cold-start latency for CLI commands, which adds up when the agent runs frequent tool calls. ## Configure systemd for Always-On Operation The onboarding wizard creates a basic systemd unit, but you should review and harden it. The service file lives at `/etc/systemd/system/openclaw.service`: ``` [Unit] Description=OpenClaw Gateway After=network.target [Service] Type=simple User=pi WorkingDirectory=/home/pi ExecStart=/usr/local/bin/openclaw gateway start Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` Key settings here: `Restart=always` ensures the gateway comes back after crashes or OOM kills. `RestartSec=5` adds a brief delay to avoid rapid restart loops. The `After=network.target` dependency makes sure networking is available before the gateway tries to reach cloud APIs. Enable and start the service: ``` sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw ``` Check that it's running: ``` sudo systemctl status openclaw ``` To follow logs in real time: ``` journalctl -u openclaw -f ``` If the service fails repeatedly, check the last 100 log lines for specifics: ``` journalctl -u openclaw --no-pager -n 100 ``` ### Handling WiFi Drops Headless Pis on WiFi sometimes lose connectivity when the adapter enters power-saving mode. If you see intermittent API failures in the logs, disable WiFi power management: ``` sudo iwconfig wlan0 power off ``` For a permanent fix, add a NetworkManager dispatcher script or use Ethernet. An always-on agent needs an always-on connection. ## Harden with Docker Running OpenClaw directly on the host means the agent's tool executions share the same filesystem and network namespace as everything else on the Pi. Docker adds a layer of isolation that limits blast radius if a tool call goes wrong. Install Docker on the Pi: ``` curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER ``` Create a `docker-compose.yml` with security-hardened settings: ```yaml services: openclaw: image: openclaw/gateway:latest restart: always ports: - "127.0.0.1:18789:18789" security_opt: - no-new-privileges:true read_only: true tmpfs: - /tmp env_file: - .env.secrets ``` Three things to notice in this configuration: **Port binding to 127.0.0.1.** The `127.0.0.1:18789:18789` binding means the gateway only listens on localhost, not on all interfaces. Without this, the default `0.0.0.0` binding exposes port 18789 to every device on your network with no authentication. You can verify this is working correctly with `ss -tlnp | grep 18789`, which should show only `127.0.0.1:18789`. **Read-only filesystem.** The `read_only: true` flag makes the container's filesystem immutable. Combined with `tmpfs: /tmp` for temporary scratch space, this prevents unauthorized modifications to the OpenClaw binary or configuration from within the container. **No privilege escalation.** The `no-new-privileges:true` security option prevents processes inside the container from gaining additional privileges after startup. If a tool execution is compromised, it can't escalate to root. Store your API keys and gateway token in `.env.secrets` with restrictive permissions: ``` chmod 600 .env.secrets ``` Start the container: ``` docker compose up -d ``` ## Lock Down the Network Docker isolation protects against container-level threats, but network-level hardening prevents unauthorized access to the Pi itself. ### UFW Firewall Rules Configure UFW to deny all incoming traffic by default, then allow only SSH: ``` sudo ufw default deny incoming sudo ufw allow ssh sudo ufw enable sudo ufw status verbose ``` Since the gateway binds to `127.0.0.1`, you don't need a UFW rule for port 18789. The SSH tunnel handles remote access, and the firewall blocks direct connections from other devices. ### Gateway Token Security The OpenClaw gateway token controls access to your agent. Generate a strong one with at least 32 random characters: ``` openssl rand -hex 32 ``` Store this in your `.env.secrets` file, never in version control. Rotate gateway tokens monthly and API keys quarterly. A compromised token gives full control over your agent's tool execution. ### VLAN Isolation For stronger isolation, put the Pi on its own VLAN. Configure your router to create a dedicated network segment for AI agent hardware, with firewall rules that restrict the Pi's access to the internet and any specific services it needs (like Home Assistant). Block all inbound internet connections to the Pi. This is especially relevant if your agent has tools that interact with home automation, file systems, or external services. A compromised agent on an isolated VLAN can't pivot to other devices on your home network. ### Run a Security Audit OpenClaw includes a built-in security audit tool: ``` openclaw security audit ``` This checks your configuration for common issues like exposed ports, weak tokens, and overly permissive tool access. For automated remediation of straightforward issues: ``` openclaw security audit --fix ``` ## Persistent Storage with Fastio A headless Pi agent generates outputs: research files, processed data, reports, configuration backups. Storing everything locally on the Pi creates a single point of failure. The SD card or NVMe drive is the only copy, and Pi hardware isn't designed for archival storage. You have several options for persistent storage. Local NAS or NFS mounts keep data on your network. S3-compatible object storage (MinIO, Backblaze B2) works for cold storage. For agent workflows where outputs need to be shared with humans or other agents, [Fastio](https://fast.io) provides workspaces built for that handoff. Fastio workspaces let an agent upload files, organize them into folders, and share them through purpose-built Send, Receive, and Exchange workflows. When Intelligence Mode is enabled, uploaded files are automatically indexed for semantic search and citation-backed chat, so a human reviewer can ask questions about the agent's output without downloading and reading every file. The [Fastio MCP server](/storage-for-agents/) exposes workspace operations through Streamable HTTP, which means your OpenClaw agent can interact with Fastio workspaces through MCP tool calls. Upload research results, create shares for client delivery, or pull files from Google Drive and Dropbox into a workspace without local I/O through URL Import. Fastio offers Starter, Business, and Growth plans with a 14-day Business Trial (card required; see [pricing](/pricing/)). For a headless Pi running an agent, that provides ample persistent cloud storage before you need to think about cleanup. When the agent's work is ready for human review, [ownership transfer](/storage-for-agents/) lets the agent hand off an entire organization, including workspaces, shares, and permissions, to a human account while retaining admin access for ongoing maintenance. ## Frequently asked questions ### How do I run OpenClaw without a monitor? Flash Raspberry Pi OS Lite (64-bit) with SSH enabled in the Raspberry Pi Imager settings. Connect via SSH after boot, install OpenClaw with the --install-daemon flag, and access the dashboard through an SSH tunnel on port 18789. No monitor, keyboard, or desktop environment needed. ### How do I secure OpenClaw on Raspberry Pi? Layer your defenses: bind the gateway to 127.0.0.1 instead of 0.0.0.0, run inside Docker with read-only filesystem and no-new-privileges flags, configure UFW to deny all incoming traffic except SSH, generate a 32-character gateway token, and rotate credentials monthly. Optionally isolate the Pi on a dedicated VLAN. ### Can I run OpenClaw in Docker on Raspberry Pi? Yes. Install Docker on your Pi, create a docker-compose.yml with security hardening options (read_only, no-new-privileges, localhost port binding), and store credentials in a .env.secrets file with chmod 600 permissions. The container adds isolation between OpenClaw's tool executions and the host OS. ### What Raspberry Pi model works best for OpenClaw? Raspberry Pi 5 with 8 GB RAM is the recommended baseline. The Pi 4 with 4 GB works but may struggle with multiple concurrent tool calls. Use an NVMe SSD via the M.2 HAT instead of an SD card for better performance with OpenClaw's SQLite database operations. ### How much does it cost to run OpenClaw on a Raspberry Pi? Hardware costs about $80 for a Pi 5 (8 GB) plus $20-30 for an NVMe drive and case with fan. Electricity runs $4 to published pricing at typical residential rates. The ongoing cost is primarily the cloud API usage for the LLM provider you connect to OpenClaw. ## About Fast.io Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.