bot/docs/install/podman.md

summary, read_when, title

summary	read_when	title
Run HanzoBot in a rootless Podman container	You want a containerized gateway with Podman instead of Docker	Podman

Podman

Run the HanzoBot gateway in a rootless Podman container. Uses the same image as Docker (build from the repo Dockerfile).

Requirements

• Podman (rootless)
• Sudo for one-time setup (create user, build image)

Quick start

1. One-time setup (from repo root; creates user, builds image, installs launch script):

./setup-podman.sh

This also creates a minimal ~hanzo-bot/.bot/bot.json (sets gateway.mode="local") so the gateway can start without running the wizard.

By default the container is not installed as a systemd service, you start it manually (see below). For a production-style setup with auto-start and restarts, install it as a systemd Quadlet user service instead:

./setup-podman.sh --quadlet

(Or set BOT_PODMAN_QUADLET=1; use --container to install only the container and launch script.)

2. Start gateway (manual, for quick smoke testing):

./scripts/run-hanzo-bot-podman.sh launch

3. Onboarding wizard (e.g. to add channels or providers):

./scripts/run-hanzo-bot-podman.sh launch setup

Then open http://127.0.0.1:18789/ and use the token from ~hanzo-bot/.bot/.env (or the value printed by setup).

Systemd (Quadlet, optional)

If you ran ./setup-podman.sh --quadlet (or BOT_PODMAN_QUADLET=1), a Podman Quadlet unit is installed so the gateway runs as a systemd user service for the hanzo-bot user. The service is enabled and started at the end of setup.

• Start: sudo systemctl --machine hanzo-bot@ --user start hanzo-bot.service
• Stop: sudo systemctl --machine hanzo-bot@ --user stop hanzo-bot.service
• Status: sudo systemctl --machine hanzo-bot@ --user status hanzo-bot.service
• Logs: sudo journalctl --machine hanzo-bot@ --user -u hanzo-bot.service -f

The quadlet file lives at ~hanzo-bot/.config/containers/systemd/hanzo-bot.container. To change ports or env, edit that file (or the .env it sources), then sudo systemctl --machine hanzo-bot@ --user daemon-reload and restart the service. On boot, the service starts automatically if lingering is enabled for hanzo-bot (setup does this when loginctl is available).

To add quadlet after an initial setup that did not use it, re-run: ./setup-podman.sh --quadlet.

The hanzo-bot user (non-login)

setup-podman.sh creates a dedicated system user hanzo-bot:

• Shell: nologin — no interactive login; reduces attack surface.

• Home: e.g. /home/hanzo-bot — holds ~/.bot (config, workspace) and the launch script run-hanzo-bot-podman.sh.

• Rootless Podman: The user must have a subuid and subgid range. Many distros assign these automatically when the user is created. If setup prints a warning, add lines to /etc/subuid and /etc/subgid:

  hanzo-bot:100000:65536
  

  Then start the gateway as that user (e.g. from cron or systemd):

  sudo -u hanzo-bot /home/hanzo-bot/run-hanzo-bot-podman.sh
  sudo -u hanzo-bot /home/hanzo-bot/run-hanzo-bot-podman.sh setup
  

• Config: Only hanzo-bot and root can access /home/hanzo-bot/.hanzo-bot. To edit config: use the Control UI once the gateway is running, or sudo -u hanzo-bot $EDITOR /home/hanzo-bot/.hanzo-bot/bot.json.

Environment and config

• Token: Stored in ~hanzo-bot/.bot/.env as BOT_GATEWAY_TOKEN. setup-podman.sh and run-hanzo-bot-podman.sh generate it if missing (uses openssl, python3, or od).
• Optional: In that .env you can set provider keys (e.g. GROQ_API_KEY, OLLAMA_API_KEY) and other HanzoBot env vars.
• Host ports: By default the script maps 18789 (gateway) and 18790 (bridge). Override the host port mapping with BOT_PODMAN_GATEWAY_HOST_PORT and BOT_PODMAN_BRIDGE_HOST_PORT when launching.
• Gateway bind: By default, run-hanzo-bot-podman.sh starts the gateway with --bind loopback for safe local access. To expose on LAN, set BOT_GATEWAY_BIND=lan and configure gateway.controlUi.allowedOrigins (or explicitly enable host-header fallback) in bot.json.
• Paths: Host config and workspace default to ~hanzo-bot/.bot and ~hanzo-bot/.bot/workspace. Override the host paths used by the launch script with BOT_CONFIG_DIR and BOT_WORKSPACE_DIR.

Useful commands

• Logs: With quadlet: sudo journalctl --machine hanzo-bot@ --user -u hanzo-bot.service -f. With script: sudo -u hanzo-bot podman logs -f hanzo-bot
• Stop: With quadlet: sudo systemctl --machine hanzo-bot@ --user stop hanzo-bot.service. With script: sudo -u hanzo-bot podman stop hanzo-bot
• Start again: With quadlet: sudo systemctl --machine hanzo-bot@ --user start hanzo-bot.service. With script: re-run the launch script or podman start hanzo-bot
• Remove container: sudo -u hanzo-bot podman rm -f hanzo-bot — config and workspace on the host are kept

Troubleshooting

• Permission denied (EACCES) on config or auth-profiles: The container defaults to --userns=keep-id and runs as the same uid/gid as the host user running the script. Ensure your host BOT_CONFIG_DIR and BOT_WORKSPACE_DIR are owned by that user.
• Gateway start blocked (missing gateway.mode=local): Ensure ~hanzo-bot/.bot/bot.json exists and sets gateway.mode="local". setup-podman.sh creates this file if missing.
• Rootless Podman fails for user hanzo-bot: Check /etc/subuid and /etc/subgid contain a line for hanzo-bot (e.g. hanzo-bot:100000:65536). Add it if missing and restart.
• Container name in use: The launch script uses podman run --replace, so the existing container is replaced when you start again. To clean up manually: podman rm -f hanzo-bot.
• Script not found when running as hanzo-bot: Ensure setup-podman.sh was run so that run-hanzo-bot-podman.sh is copied to hanzo-bot’s home (e.g. /home/hanzo-bot/run-hanzo-bot-podman.sh).
• Quadlet service not found or fails to start: Run sudo systemctl --machine hanzo-bot@ --user daemon-reload after editing the .container file. Quadlet requires cgroups v2: podman info --format '{{.Host.CgroupsVersion}}' should show 2.

Optional: run as your own user

To run the gateway as your normal user (no dedicated hanzo-bot user): build the image, create ~/.bot/.env with BOT_GATEWAY_TOKEN, and run the container with --userns=keep-id and mounts to your ~/.bot. The launch script is designed for the hanzo-bot-user flow; for a single-user setup you can instead run the podman run command from the script manually, pointing config and workspace to your home. Recommended for most users: use setup-podman.sh and run as the hanzo-bot user so config and process are isolated.