Skip to main content
Run the FluffBuzz Gateway in a rootless Podman container, managed by your current non-root user. The intended model is:
  • Podman runs the gateway container.
  • Your host fluffbuzz CLI is the control plane.
  • Persistent state lives on the host under ~/.fluffbuzz by default.
  • Day-to-day management uses fluffbuzz --container <name> ... instead of sudo -u fluffbuzz, podman exec, or a separate service user.

​
Prerequisites

  • Podman in rootless mode
  • FluffBuzz CLI installed on the host
  • Optional: systemd --user if you want Quadlet-managed auto-start
  • Optional: sudo only if you want loginctl enable-linger "$(whoami)" for boot persistence on a headless host

​
Quick start

1

One-time setup

From the repo root, run ./scripts/podman/setup.sh.
2

Start the Gateway container

Start the container with ./scripts/run-fluffbuzz-podman.sh launch.
3

Run onboarding inside the container

Run ./scripts/run-fluffbuzz-podman.sh launch setup, then open http://127.0.0.1:18789/.
4

Manage the running container from the host CLI

Set FLUFFBUZZ_CONTAINER=fluffbuzz, then use normal fluffbuzz commands from the host.
Setup details:
  • ./scripts/podman/setup.sh builds fluffbuzz:local in your rootless Podman store by default, or uses FLUFFBUZZ_IMAGE / FLUFFBUZZ_PODMAN_IMAGE if you set one.
  • It creates ~/.fluffbuzz/fluffbuzz.json with gateway.mode: "local" if missing.
  • It creates ~/.fluffbuzz/.env with FLUFFBUZZ_GATEWAY_TOKEN if missing.
  • For manual launches, the helper reads only a small allowlist of Podman-related keys from ~/.fluffbuzz/.env and passes explicit runtime env vars to the container; it does not hand the full env file to Podman.
Quadlet-managed setup: 
./scripts/podman/setup.sh --quadlet
Quadlet is a Linux-only option because it depends on systemd user services. You can also set FLUFFBUZZ_PODMAN_QUADLET=1. Optional build/setup env vars:
  • FLUFFBUZZ_IMAGE or FLUFFBUZZ_PODMAN_IMAGE — use an existing/pulled image instead of building fluffbuzz:local
  • FLUFFBUZZ_DOCKER_APT_PACKAGES — install extra apt packages during image build
  • FLUFFBUZZ_EXTENSIONS — pre-install plugin dependencies at build time
Container start: 
./scripts/run-fluffbuzz-podman.sh launch
The script starts the container as your current uid/gid with --userns=keep-id and bind-mounts your FluffBuzz state into the container. Onboarding: 
./scripts/run-fluffbuzz-podman.sh launch setup
Then open http://127.0.0.1:18789/ and use the token from ~/.fluffbuzz/.env. Host CLI default: 
export FLUFFBUZZ_CONTAINER=fluffbuzz
Then commands such as these will run inside that container automatically: 
fluffbuzz dashboard --no-open
fluffbuzz gateway status --deep   # includes extra service scan
fluffbuzz doctor
fluffbuzz channels login
On macOS, Podman machine may make the browser appear non-local to the gateway. If the Control UI reports device-auth errors after launch, use the Tailscale guidance in Podman + Tailscale.

​
Podman + Tailscale

For HTTPS or remote browser access, follow the main Tailscale docs. Podman-specific note:
  • Keep the Podman publish host at 127.0.0.1.
  • Prefer host-managed tailscale serve over fluffbuzz gateway --tailscale serve.
  • On macOS, if local browser device-auth context is unreliable, use Tailscale access instead of ad hoc local tunnel workarounds.
See:

​
Systemd (Quadlet, optional)

If you ran ./scripts/podman/setup.sh --quadlet, setup installs a Quadlet file at: 
~/.config/containers/systemd/fluffbuzz.container
Useful commands:
  • Start: systemctl --user start fluffbuzz.service
  • Stop: systemctl --user stop fluffbuzz.service
  • Status: systemctl --user status fluffbuzz.service
  • Logs: journalctl --user -u fluffbuzz.service -f
After editing the Quadlet file: 
systemctl --user daemon-reload
systemctl --user restart fluffbuzz.service
For boot persistence on SSH/headless hosts, enable lingering for your current user: 
sudo loginctl enable-linger "$(whoami)"

​
Config, env, and storage

  • Config dir: ~/.fluffbuzz
  • Workspace dir: ~/.fluffbuzz/workspace
  • Token file: ~/.fluffbuzz/.env
  • Launch helper: ./scripts/run-fluffbuzz-podman.sh
The launch script and Quadlet bind-mount host state into the container:
  • FLUFFBUZZ_CONFIG_DIR -> /home/node/.fluffbuzz
  • FLUFFBUZZ_WORKSPACE_DIR -> /home/node/.fluffbuzz/workspace
By default those are host directories, not anonymous container state, so fluffbuzz.json, per-agent auth-profiles.json, channel/provider state, sessions, and workspace survive container replacement. The Podman setup also seeds gateway.controlUi.allowedOrigins for 127.0.0.1 and localhost on the published gateway port so the local dashboard works with the container’s non-loopback bind. Useful env vars for the manual launcher:
  • FLUFFBUZZ_PODMAN_CONTAINER — container name (fluffbuzz by default)
  • FLUFFBUZZ_PODMAN_IMAGE / FLUFFBUZZ_IMAGE — image to run
  • FLUFFBUZZ_PODMAN_GATEWAY_HOST_PORT — host port mapped to container 18789
  • FLUFFBUZZ_PODMAN_BRIDGE_HOST_PORT — host port mapped to container 18790
  • FLUFFBUZZ_PODMAN_PUBLISH_HOST — host interface for published ports; default is 127.0.0.1
  • FLUFFBUZZ_GATEWAY_BIND — gateway bind mode inside the container; default is lan
  • FLUFFBUZZ_PODMAN_USERNS — keep-id (default), auto, or host
The manual launcher reads ~/.fluffbuzz/.env before finalizing container/image defaults, so you can persist these there. If you use a non-default FLUFFBUZZ_CONFIG_DIR or FLUFFBUZZ_WORKSPACE_DIR, set the same variables for both ./scripts/podman/setup.sh and later ./scripts/run-fluffbuzz-podman.sh launch commands. The repo-local launcher does not persist custom path overrides across shells. Quadlet note:
  • The generated Quadlet service intentionally keeps a fixed, hardened default shape: 127.0.0.1 published ports, --bind lan inside the container, and keep-id user namespace.
  • It pins FLUFFBUZZ_NO_RESPAWN=1, Restart=on-failure, and TimeoutStartSec=300.
  • It publishes both 127.0.0.1:18789:18789 (gateway) and 127.0.0.1:18790:18790 (bridge).
  • It reads ~/.fluffbuzz/.env as a runtime EnvironmentFile for values such as FLUFFBUZZ_GATEWAY_TOKEN, but it does not consume the manual launcher’s Podman-specific override allowlist.
  • If you need custom publish ports, publish host, or other container-run flags, use the manual launcher or edit ~/.config/containers/systemd/fluffbuzz.container directly, then reload and restart the service.

​
Useful commands

  • Container logs: podman logs -f fluffbuzz
  • Stop container: podman stop fluffbuzz
  • Remove container: podman rm -f fluffbuzz
  • Open dashboard URL from host CLI: fluffbuzz dashboard --no-open
  • Health/status via host CLI: fluffbuzz gateway status --deep (RPC probe + extra service scan)

​
Troubleshooting

  • Permission denied (EACCES) on config or workspace: The container runs with --userns=keep-id and --user <your uid>:<your gid> by default. Ensure the host config/workspace paths are owned by your current user.
  • Gateway start blocked (missing gateway.mode=local): Ensure ~/.fluffbuzz/fluffbuzz.json exists and sets gateway.mode="local". scripts/podman/setup.sh creates this if missing.
  • Container CLI commands hit the wrong target: Use fluffbuzz --container <name> ... explicitly, or export FLUFFBUZZ_CONTAINER=<name> in your shell.
  • fluffbuzz update fails with --container: Expected. Rebuild/pull the image, then restart the container or the Quadlet service.
  • Quadlet service does not start: Run systemctl --user daemon-reload, then systemctl --user start fluffbuzz.service. On headless systems you may also need sudo loginctl enable-linger "$(whoami)".
  • SELinux blocks bind mounts: Leave the default mount behavior alone; the launcher auto-adds :Z on Linux when SELinux is enforcing or permissive.