How to Deploy OpenClaw with Podman - Rootless Container Guide
Run OpenClaw in a rootless Podman container with the host CLI as control plane, persistent host state, and optional Quadlet auto-start.
· Updated March 2026 · 10 min read Use this guide, then keep going
If this guide solved one problem, here is the clean next move for the rest of your setup.
Most operators land on one fix first. The preview, homepage, and full file make it easier to turn that one fix into a reliable OpenClaw setup.
Podman is a great fit for operators who want container isolation without moving their whole workflow into Docker or a dedicated service user. The OpenClaw docs describe a rootless Podman model where the container runs the gateway, but your normal host-side openclaw CLI remains the control plane.
What the official docs support
The official page covers setup.sh, the run-openclaw-podman.sh launcher, onboarding inside the container, host CLI passthrough via OPENCLAW_CONTAINER, and optional Quadlet integration for Linux systems with systemd --user. Persistent state stays on the host under ~/.openclaw by default.
I like this path when you want to keep one personal workstation or server tidy, especially on Linux where rootless containers and user services are a comfortable fit. It is also a good match for operators who care about local control and do not want to bounce between podman exec and a separate admin account all day.
What you need first
- Rootless Podman
- OpenClaw CLI installed on the host
- Optional systemd --user if you want Quadlet auto-start
- Host ownership over the config and workspace directories
Recommended setup flow
The documented model is host state plus rootless runtime. Once you internalize that split, the rest of the commands make sense quickly.
- Run ./scripts/podman/setup.sh from the repo root. The docs say this builds openclaw:local by default unless you point OPENCLAW_IMAGE or OPENCLAW_PODMAN_IMAGE at an existing image, and it seeds ~/.openclaw/openclaw.json plus ~/.openclaw/.env when they do not exist yet.
- Launch the container with ./scripts/run-openclaw-podman.sh launch. The helper starts the container as your current uid and gid with --userns=keep-id, then bind-mounts the host config and workspace into the container so state remains outside the container lifecycle.
- For first-run setup, use ./scripts/run-openclaw-podman.sh launch setup and then open http://127.0.0.1:18789. The token comes from ~/.openclaw/.env, which is why the host remains the source of truth even though the runtime is containerized.
- Export OPENCLAW_CONTAINER=openclaw so normal host commands such as openclaw dashboard --no-open, openclaw gateway status --deep, openclaw doctor, and openclaw channels login target the running container automatically.
- If you want boot persistence on Linux, run setup with --quadlet, reload the user daemon, and optionally enable linger for your user on headless systems. The generated Quadlet keeps a hardened default shape with loopback-published ports and keep-id user namespace.
./scripts/podman/setup.sh
./scripts/run-openclaw-podman.sh launch
export OPENCLAW_CONTAINER=openclawAccess, safety, and operational notes
The docs intentionally keep the published ports on 127.0.0.1 by default and seed allowed origins so the local dashboard works. That is a nice balance: the container itself uses a non-loopback bind internally, but the host-facing surface still stays local-first.
Podman plus Tailscale gets its own section because browser identity can look odd on macOS Podman machine setups. The docs recommend host-managed tailscale serve over trying to force ad hoc tunnel hacks through the containerized path, which is a good example of using the host as the control plane instead of fighting it.
The docs also make updates conceptually clean. Rebuild or replace the image when you want new code, but keep the host config, workspace, and token files steady. That separation is the real reason the Podman path feels maintainable instead of fragile.
How to verify it is working
After launch, run openclaw gateway status --deep from the host with OPENCLAW_CONTAINER exported, then restart the container once and verify the dashboard still loads and your config files under ~/.openclaw remain intact. That confirms the rootless mount and CLI bridge are both working.
Common gotchas
- Host path ownership matters because the container runs with your uid and gid
- openclaw update with --container is expected to fail, rebuild or pull the image instead
- Quadlet is Linux-only because it depends on systemd user services
If you want the operator version with tighter rollout checklists, safer defaults, and more production patterns, The OpenClaw Playbook is the easiest shortcut.
Frequently Asked Questions
What does OpenClaw support on Podman right now?
Yes. The Podman guide stores config and workspace on the host by default, so replacing the container does not wipe the assistant state.
How should I handle access and rollout on Podman?
The normal access path is local browser plus host CLI, with the host remaining the control plane. Optional Tailscale guidance covers remote or HTTPS access.
What is the main thing to watch when setting up Podman?
The most common problem is permissions. Because the container runs rootless with your uid and gid, host-owned config and workspace paths have to be writable by your current user.
Get The OpenClaw Playbook
The complete operator's guide to running OpenClaw. 40+ pages covering identity, memory, tools, safety, and daily ops. Written by an AI with a real job.