Podman

Rootless container deployment with Podman. Dedicated system user, optional systemd Quadlet service for auto-start.

Podman offers a rootless, daemon-less alternative to Docker for running OpenClaw in containers. Unlike Docker, Podman doesn't require a persistent root daemon — containers run as regular user processes, which significantly reduces the attack surface. This makes it the preferred container runtime for security-focused Linux deployments. The setup script (`./scripts/podman/setup.sh`) creates a dedicated `openclaw` system user with a `nologin` shell, builds the container image using the same Dockerfile as Docker, and installs a launch script. The dedicated user approach means OpenClaw runs with minimal privileges — no root access, no interactive shell, just the container runtime. The user gets its own subuid/subgid range for rootless container operation. For production use, the `--quadlet` flag installs a Podman Quadlet unit — a systemd service definition that manages the container lifecycle. With Quadlet, the gateway starts automatically on boot, restarts on failure, and integrates with standard systemd tooling (journalctl for logs, systemctl for management). This is the recommended approach for always-on deployments where you want systemd's reliability guarantees. Podman is Linux-only (no macOS or Windows support for rootless mode) and requires some manual configuration that Docker handles automatically — specifically, subuid/subgid ranges must be set up for the openclaw user, and some distros may need additional packages for rootless networking. The trade-off is a more secure foundation: no root daemon, no Docker socket exposure, and full integration with Linux security frameworks like SELinux and AppArmor.

Tags: container, podman, rootless, systemd

Use Cases

  • Security-focused Linux servers where Docker's root daemon is unacceptable
  • Enterprise environments with strict container security policies requiring rootless runtimes
  • Systemd-first deployments that want native service management without Docker's overhead
  • Environments where Docker isn't installed and you prefer not to add a root daemon

Tips

  • Use --quadlet for production deployments — it gives you systemd restart policies and journald log integration
  • Check subuid/subgid with grep openclaw /etc/subuid /etc/subgid before running setup
  • Monitor with standard systemd tooling: journalctl --machine openclaw@ --user -u openclaw.service -f
  • Re-run setup with --quadlet at any time to add systemd integration after initial setup
  • Enable lingering for the openclaw user so the service starts on boot: loginctl enable-linger openclaw
  • Use OPENCLAW_EXTENSIONS env var during setup to pre-install extensions into the image

Known Issues & Gotchas

  • Linux-only — Podman rootless mode is not available on macOS or Windows
  • Subuid/subgid ranges must be configured for the openclaw user — some distros do this automatically, others require manual /etc/subuid and /etc/subgid entries
  • The setup script requires sudo for one-time user creation, but the container itself runs rootless
  • Podman CLI is mostly Docker-compatible but not 100% — some docker compose features may behave differently
  • The nologin shell on the openclaw user means you can't SSH directly to it — use sudo -u openclaw or systemd
  • If lingering isn't enabled for the openclaw user, the Quadlet service won't start on boot without an active login session

Alternatives

  • Docker
  • Ansible
  • Nix / Home Manager

Community Feedback

Podman rootless is the way to go if you care about security. No root daemon means no Docker socket attack vector.

— Reddit r/selfhosted

The Quadlet integration is clean — proper systemd service without the Docker daemon overhead. Logs go straight to journald.

— Reddit r/selfhosted

Had to manually add subuid/subgid ranges on Debian before rootless Podman would work. Not a dealbreaker but the docs should mention it more prominently.

— Reddit r/selfhosted

Frequently Asked Questions

Is Podman a drop-in replacement for Docker?

Mostly, yes. Podman uses the same Dockerfile and OCI images. The main differences are: no root daemon, slightly different networking, and Quadlet instead of Docker Compose for service management. OpenClaw provides dedicated Podman scripts that handle these differences.

Why create a dedicated openclaw user?

The dedicated user with nologin shell is a security measure. It runs the container with minimal privileges, prevents interactive access, and isolates OpenClaw's data from other system users.

How do I view logs with the Quadlet setup?

Use journalctl: sudo journalctl --machine openclaw@ --user -u openclaw.service -f. This shows real-time logs from the containerized gateway through systemd's journal.

Can I use Podman on macOS?

Podman can run on macOS via a VM, but the rootless security benefits are lost since it's running inside a Linux VM anyway. For macOS, the native install or Docker Desktop is more practical.

What if subuid/subgid ranges aren't configured?

The setup script will warn you. Add the ranges manually: echo 'openclaw:100000:65536' to both /etc/subuid and /etc/subgid. Without these, rootless Podman can't create user namespaces for container isolation.

Does agent sandboxing work with Podman?

Agent sandboxing is designed for Docker. With Podman, the gateway runs containerized but agent sandbox containers may need additional configuration. Check the OpenClaw sandboxing docs for Podman-specific notes.