OpenClaw on Rootless Podman: Secure Setup with Systemd Quadlet

Why Podman Instead of Docker?

Podman runs containers without a daemon and without root privileges. For security-conscious deployments, this is significant:

• No root daemon: Docker requires a root-level daemon process. Podman runs entirely in userspace
• Dedicated user isolation: OpenClaw runs as its own system user with no access to your personal files
• Systemd integration: Quadlet files make the gateway a proper systemd service with auto-start, restart, and logging
• Docker CLI compatible: All Podman commands mirror Docker commands — minimal learning curve

Prerequisites

• Linux with Podman installed (most distros ship it by default now)
• sudo access (for creating the dedicated user)
• cgroups v2 (required for Quadlet — check with podman info --format '{{.Host.CgroupsVersion}}')

One-Script Setup

git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Basic setup
./setup-podman.sh

# With systemd Quadlet for auto-start
./setup-podman.sh --quadlet

What the Script Does

1. Creates a dedicated openclaw system user — no login shell, isolated home directory
2. Enables systemd lingering for the user — so services run without an active login session
3. Creates config directories: ~openclaw/.openclaw/ and ~openclaw/.openclaw/workspace/
4. Generates a secure gateway token and writes it to ~openclaw/.openclaw/.env
5. Creates minimal config: ~openclaw/.openclaw/openclaw.json with gateway.mode = "local"
6. Builds the container image via podman build
7. Loads the image into the openclaw user's Podman store
8. Copies the run script to the openclaw user's home directory
9. Optionally installs Quadlet — a systemd service unit for the container

Environment Variables

# Customize the dedicated user name (default: openclaw)
OPENCLAW_PODMAN_USER=openclaw

# Override config/workspace directories
OPENCLAW_CONFIG_DIR=/custom/config/path
OPENCLAW_WORKSPACE_DIR=/custom/workspace/path

# Custom port mappings
OPENCLAW_PODMAN_GATEWAY_HOST_PORT=18789
OPENCLAW_PODMAN_BRIDGE_HOST_PORT=18790

# Force Quadlet installation
OPENCLAW_PODMAN_QUADLET=1

Starting the Gateway

Manual Start

# Run the launch script
sudo -u openclaw ~/run-openclaw-podman.sh launch

# With onboarding wizard
sudo -u openclaw ~/run-openclaw-podman.sh launch setup

Systemd Quadlet (Recommended for Production)

# Start the service
sudo systemctl --machine openclaw@ --user start openclaw.service

# Check status
sudo systemctl --machine openclaw@ --user status openclaw.service

# View logs
sudo journalctl --machine openclaw@ --user -u openclaw.service -f

# Stop
sudo systemctl --machine openclaw@ --user stop openclaw.service

With Quadlet enabled, the gateway starts automatically on boot and restarts on failure.

Security Architecture

The Podman setup provides multiple isolation layers:

• Dedicated user: The openclaw user has no sudo access and no login shell
• Rootless container: The container process runs entirely in userspace — no root required
• UID mapping: Container user IDs are mapped to a range of unprivileged host UIDs via /etc/subuid
• Filesystem isolation: Only the config and workspace directories are mounted into the container
• Network isolation: The gateway only binds to configured ports

Troubleshooting

• subuid/subgid warning: If the script warns about missing entries, add to /etc/subuid and /etc/subgid: openclaw:100000:65536
• Gateway won't start: Ensure ~openclaw/.openclaw/openclaw.json contains "gateway": { "mode": "local" }
• Quadlet not working: Verify cgroups v2 is active. On older systems, add systemd.unified_cgroup_hierarchy=1 to kernel boot parameters
• Permission denied on config files: All files under ~openclaw/.openclaw/ must be owned by the openclaw user