Docker

Docker is optional. Use it only if you want a containerized gateway or to validate the Docker flow.

Is Docker right for me?

Yes: you want an isolated, throwaway gateway environment or to run FluffBuzz on a host without local installs.
No: you are running on your own machine and just want the fastest dev loop. Use the normal install flow instead.
Sandboxing note: the default sandbox backend uses Docker when sandboxing is enabled, but sandboxing is off by default and does not require the full gateway to run in Docker. SSH and OpenShell sandbox backends are also available. See Sandboxing.

Prerequisites

Docker Desktop (or Docker Engine) + Docker Compose v2
At least 2 GB RAM for image build (pnpm install may be OOM-killed on 1 GB hosts with exit 137)
Enough disk for images and logs
If running on a VPS/public host, review Security hardening for network exposure, especially Docker DOCKER-USER firewall policy.

Containerized Gateway

Build the image

From the repo root, run the setup script:

./scripts/docker/setup.sh

This builds the gateway image locally. To use a pre-built image instead:

export FLUFFBUZZ_IMAGE="ghcr.io/fluffbuzz/fluffbuzz:latest"
./scripts/docker/setup.sh

Pre-built images are published at the GitHub Container Registry. Common tags: main, latest, <version> (e.g. 2026.2.26).

Complete onboarding

The setup script runs onboarding automatically. It will:

prompt for provider API keys
generate a gateway token and write it to .env
start the gateway via Docker Compose

During setup, pre-start onboarding and config writes run through fluffbuzz-gateway directly. fluffbuzz-cli is for commands you run after the gateway container already exists.

Open the Control UI

Open http://127.0.0.1:18789/ in your browser and paste the configured shared secret into Settings. The setup script writes a token to .env by default; if you switch the container config to password auth, use that password instead.Need the URL again?

docker compose run --rm fluffbuzz-cli dashboard --no-open

Configure channels (optional)

Use the CLI container to add messaging channels:

# WhatsApp (QR)
docker compose run --rm fluffbuzz-cli channels login

# Telegram
docker compose run --rm fluffbuzz-cli channels add --channel telegram --token "<token>"

# Discord
docker compose run --rm fluffbuzz-cli channels add --channel discord --token "<token>"

Docs: WhatsApp, Telegram, Discord

Manual flow

If you prefer to run each step yourself instead of using the setup script:

docker build -t fluffbuzz:local -f Dockerfile .
docker compose run --rm --no-deps --entrypoint node fluffbuzz-gateway \
  dist/index.js onboard --mode local --no-install-daemon
docker compose run --rm --no-deps --entrypoint node fluffbuzz-gateway \
  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'
docker compose up -d fluffbuzz-gateway

Run docker compose from the repo root. If you enabled FLUFFBUZZ_EXTRA_MOUNTS or FLUFFBUZZ_HOME_VOLUME, the setup script writes docker-compose.extra.yml; include it with -f docker-compose.yml -f docker-compose.extra.yml.

Because fluffbuzz-cli shares fluffbuzz-gateway’s network namespace, it is a post-start tool. Before docker compose up -d fluffbuzz-gateway, run onboarding and setup-time config writes through fluffbuzz-gateway with --no-deps --entrypoint node.

Environment variables

The setup script accepts these optional environment variables:

Variable	Purpose
`FLUFFBUZZ_IMAGE`	Use a remote image instead of building locally
`FLUFFBUZZ_DOCKER_APT_PACKAGES`	Install extra apt packages during build (space-separated)
`FLUFFBUZZ_EXTENSIONS`	Pre-install plugin deps at build time (space-separated names)
`FLUFFBUZZ_EXTRA_MOUNTS`	Extra host bind mounts (comma-separated `source:target[:opts]`)
`FLUFFBUZZ_HOME_VOLUME`	Persist `/home/node` in a named Docker volume
`FLUFFBUZZ_SANDBOX`	Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`)
`FLUFFBUZZ_DOCKER_SOCKET`	Override Docker socket path

Health checks

Container probe endpoints (no auth required):

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

The Docker image includes a built-in HEALTHCHECK that pings /healthz. If checks keep failing, Docker marks the container as unhealthy and orchestration systems can restart or replace it. Authenticated deep health snapshot:

docker compose exec fluffbuzz-gateway node dist/index.js health --token "$FLUFFBUZZ_GATEWAY_TOKEN"

LAN vs loopback

scripts/docker/setup.sh defaults FLUFFBUZZ_GATEWAY_BIND=lan so host access to http://127.0.0.1:18789 works with Docker port publishing.

lan (default): host browser and host CLI can reach the published gateway port.
loopback: only processes inside the container network namespace can reach the gateway directly.

Use bind mode values in gateway.bind (lan / loopback / custom / tailnet / auto), not host aliases like 0.0.0.0 or 127.0.0.1.

Storage and persistence

Docker Compose bind-mounts FLUFFBUZZ_CONFIG_DIR to /home/node/.fluffbuzz and FLUFFBUZZ_WORKSPACE_DIR to /home/node/.fluffbuzz/workspace, so those paths survive container replacement. That mounted config directory is where FluffBuzz keeps:

fluffbuzz.json for behavior config
agents/<agentId>/agent/auth-profiles.json for stored provider OAuth/API-key auth
.env for env-backed runtime secrets such as FLUFFBUZZ_GATEWAY_TOKEN

For full persistence details on VM deployments, see Docker VM Runtime - What persists where. Disk growth hotspots: watch media/, session JSONL files, cron/runs/*.jsonl, and rolling file logs under /tmp/fluffbuzz/.

Shell helpers (optional)

For easier day-to-day Docker management, install FluffDock:

mkdir -p ~/.fluffdock && curl -sL https://raw.githubusercontent.com/fluffbuzz/fluffbuzz/main/scripts/fluffdock/fluffdock-helpers.sh -o ~/.fluffdock/fluffdock-helpers.sh
echo 'source ~/.fluffdock/fluffdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

If you installed FluffDock from the older scripts/shell-helpers/fluffdock-helpers.sh raw path, rerun the install command above so your local helper file tracks the new location. Then use fluffdock-start, fluffdock-stop, fluffdock-dashboard, etc. Run fluffdock-help for all commands. See FluffDock for the full helper guide.

Enable agent sandbox for Docker gateway

export FLUFFBUZZ_SANDBOX=1
./scripts/docker/setup.sh

Custom socket path (e.g. rootless Docker):

export FLUFFBUZZ_SANDBOX=1
export FLUFFBUZZ_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

The script mounts docker.sock only after sandbox prerequisites pass. If sandbox setup cannot complete, the script resets agents.defaults.sandbox.mode to off.

Automation / CI (non-interactive)

Disable Compose pseudo-TTY allocation with -T:

docker compose run -T --rm fluffbuzz-cli gateway probe
docker compose run -T --rm fluffbuzz-cli devices list --json

Shared-network security note

fluffbuzz-cli uses network_mode: "service:fluffbuzz-gateway" so CLI commands can reach the gateway over 127.0.0.1. Treat this as a shared trust boundary. The compose config drops NET_RAW/NET_ADMIN and enables no-new-privileges on fluffbuzz-cli.

Permissions and EACCES

The image runs as node (uid 1000). If you see permission errors on /home/node/.fluffbuzz, make sure your host bind mounts are owned by uid 1000:

sudo chown -R 1000:1000 /path/to/fluffbuzz-config /path/to/fluffbuzz-workspace

Faster rebuilds

Order your Dockerfile so dependency layers are cached. This avoids re-running pnpm install unless lockfiles change:

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

Power-user container options

The default image is security-first and runs as non-root node. For a more full-featured container:

Persist /home/node: export FLUFFBUZZ_HOME_VOLUME="fluffbuzz_home"
Bake system deps: export FLUFFBUZZ_DOCKER_APT_PACKAGES="git curl jq"

Install Playwright browsers:

docker compose run --rm fluffbuzz-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

Persist browser downloads: set PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright and use FLUFFBUZZ_HOME_VOLUME or FLUFFBUZZ_EXTRA_MOUNTS.

OpenAI Codex OAuth (headless Docker)

If you pick OpenAI Codex OAuth in the wizard, it opens a browser URL. In Docker or headless setups, copy the full redirect URL you land on and paste it back into the wizard to finish auth.

Base image metadata

The main Docker image uses node:24-bookworm and publishes OCI base-image annotations including org.opencontainers.image.base.name, org.opencontainers.image.source, and others. See OCI image annotations.

Running on a VPS?

See Hetzner (Docker VPS) and Docker VM Runtime for shared VM deployment steps including binary baking, persistence, and updates.

Agent Sandbox

When agents.defaults.sandbox is enabled with the Docker backend, the gateway runs agent tool execution (shell, file read/write, etc.) inside isolated Docker containers while the gateway itself stays on the host. This gives you a hard wall around untrusted or multi-tenant agent sessions without containerizing the entire gateway. Sandbox scope can be per-agent (default), per-session, or shared. Each scope gets its own workspace mounted at /workspace. You can also configure allow/deny tool policies, network isolation, resource limits, and browser containers. For full configuration, images, security notes, and multi-agent profiles, see:

Sandboxing — complete sandbox reference
OpenShell — interactive shell access to sandbox containers
Multi-Agent Sandbox and Tools — per-agent overrides

Quick enable

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}

Build the default sandbox image:

scripts/sandbox-setup.sh

Troubleshooting

Image missing or sandbox container not starting

Build the sandbox image with scripts/sandbox-setup.sh or set agents.defaults.sandbox.docker.image to your custom image. Containers are auto-created per session on demand.

Permission errors in sandbox

Set docker.user to a UID:GID that matches your mounted workspace ownership, or chown the workspace folder.

Custom tools not found in sandbox

FluffBuzz runs commands with sh -lc (login shell), which sources /etc/profile and may reset PATH. Set docker.env.PATH to prepend your custom tool paths, or add a script under /etc/profile.d/ in your Dockerfile.

OOM-killed during image build (exit 137)

The VM needs at least 2 GB RAM. Use a larger machine class and retry.

Unauthorized or pairing required in Control UI

Fetch a fresh dashboard link and approve the browser device:

docker compose run --rm fluffbuzz-cli dashboard --no-open
docker compose run --rm fluffbuzz-cli devices list
docker compose run --rm fluffbuzz-cli devices approve <requestId>

More detail: Dashboard, Devices.

Gateway target shows ws://172.x.x.x or pairing errors from Docker CLI

Reset gateway mode and bind:

docker compose run --rm fluffbuzz-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm fluffbuzz-cli devices list --url ws://127.0.0.1:18789

Install Overview — all installation methods
Podman — Podman alternative to Docker
FluffDock — Docker Compose community setup
Updating — keeping FluffBuzz up to date
Configuration — gateway configuration after install

Install overview

Containers

Hosting

Maintenance

Is Docker right for me?

Prerequisites

Containerized Gateway

Manual flow

Environment variables

Health checks

LAN vs loopback

Storage and persistence

Shell helpers (optional)

Running on a VPS?

Agent Sandbox

Quick enable

Troubleshooting

​Is Docker right for me?

​Prerequisites

​Containerized Gateway

​Manual flow

​Environment variables

​Health checks

​LAN vs loopback

​Storage and persistence

​Shell helpers (optional)

​Running on a VPS?

​Agent Sandbox

​Quick enable

​Troubleshooting

​Related

Is Docker right for me?

Prerequisites

Containerized Gateway

Manual flow

Environment variables

Health checks

LAN vs loopback

Storage and persistence

Shell helpers (optional)

Running on a VPS?

Agent Sandbox

Quick enable

Troubleshooting

Related