FluffBuzz on Hetzner (Docker, Production VPS Guide)

Goal

Run a persistent FluffBuzz Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior. If you want “FluffBuzz 24/7 for ~$5”, this is the simplest reliable setup. Hetzner pricing changes; pick the smallest Debian/Ubuntu VPS and scale up if you hit OOMs. Security model reminder:

Company-shared agents are fine when everyone is in the same trust boundary and the runtime is business-only.
Keep strict separation: dedicated VPS/runtime + dedicated accounts; no personal Apple/Google/browser/password-manager profiles on that host.
If users are adversarial to each other, split by gateway/host/OS user.

See Security and VPS hosting.

What are we doing (simple terms)?

Rent a small Linux server (Hetzner VPS)
Install Docker (isolated app runtime)
Start the FluffBuzz Gateway in Docker
Persist ~/.fluffbuzz + ~/.fluffbuzz/workspace on the host (survives restarts/rebuilds)
Access the Control UI from your laptop via an SSH tunnel

That mounted ~/.fluffbuzz state includes fluffbuzz.json, per-agent agents/<agentId>/agent/auth-profiles.json, and .env. The Gateway can be accessed via:

SSH port forwarding from your laptop
Direct port exposure if you manage firewalling and tokens yourself

This guide assumes Ubuntu or Debian on Hetzner.
If you are on another Linux VPS, map packages accordingly. For the generic Docker flow, see Docker.

Quick path (experienced operators)

Provision Hetzner VPS
Install Docker
Clone FluffBuzz repository
Create persistent host directories
Configure .env and docker-compose.yml
Bake required binaries into the image
docker compose up -d
Verify persistence and Gateway access

What you need

Hetzner VPS with root access
SSH access from your laptop
Basic comfort with SSH + copy/paste
~20 minutes
Docker and Docker Compose
Model auth credentials
Optional provider credentials
- WhatsApp QR
- Telegram bot token
- Gmail OAuth

Provision the VPS

Create an Ubuntu or Debian VPS in Hetzner.Connect as root:

ssh root@YOUR_VPS_IP

This guide assumes the VPS is stateful. Do not treat it as disposable infrastructure.

Install Docker (on the VPS)

apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh

Verify:

docker --version
docker compose version

Clone the FluffBuzz repository

git clone https://github.com/fluffbuzz/fluffbuzz.git
cd fluffbuzz

This guide assumes you will build a custom image to guarantee binary persistence.

Create persistent host directories

Docker containers are ephemeral. All long-lived state must live on the host.

mkdir -p /root/.fluffbuzz/workspace

# Set ownership to the container user (uid 1000):
chown -R 1000:1000 /root/.fluffbuzz

Configure environment variables

Create .env in the repository root.

FLUFFBUZZ_IMAGE=fluffbuzz:latest
FLUFFBUZZ_GATEWAY_TOKEN=
FLUFFBUZZ_GATEWAY_BIND=lan
FLUFFBUZZ_GATEWAY_PORT=18789

FLUFFBUZZ_CONFIG_DIR=/root/.fluffbuzz
FLUFFBUZZ_WORKSPACE_DIR=/root/.fluffbuzz/workspace

GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.fluffbuzz

Leave FLUFFBUZZ_GATEWAY_TOKEN blank unless you explicitly want to manage it through .env; FluffBuzz writes a random gateway token to config on first start. Generate a keyring password and paste it into GOG_KEYRING_PASSWORD:

openssl rand -hex 32

Do not commit this file.This .env file is for container/runtime env such as FLUFFBUZZ_GATEWAY_TOKEN. Stored provider OAuth/API-key auth lives in the mounted ~/.fluffbuzz/agents/<agentId>/agent/auth-profiles.json.

Docker Compose configuration

Create or update docker-compose.yml.

services:
  fluffbuzz-gateway:
    image: ${FLUFFBUZZ_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - FLUFFBUZZ_GATEWAY_BIND=${FLUFFBUZZ_GATEWAY_BIND}
      - FLUFFBUZZ_GATEWAY_PORT=${FLUFFBUZZ_GATEWAY_PORT}
      - FLUFFBUZZ_GATEWAY_TOKEN=${FLUFFBUZZ_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${FLUFFBUZZ_CONFIG_DIR}:/home/node/.fluffbuzz
      - ${FLUFFBUZZ_WORKSPACE_DIR}:/home/node/.fluffbuzz/workspace
    ports:
      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${FLUFFBUZZ_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${FLUFFBUZZ_GATEWAY_BIND}",
        "--port",
        "${FLUFFBUZZ_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]

--allow-unconfigured is only for bootstrap convenience, it is not a replacement for a proper gateway configuration. Still set auth (gateway.auth.token or password) and use safe bind settings for your deployment.

Shared Docker VM runtime steps

Use the shared runtime guide for the common Docker host flow:

Hetzner-specific access

After the shared build and launch steps, tunnel from your laptop:

ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

Open:http://127.0.0.1:18789/Paste the configured shared secret. This guide uses the gateway token by default; if you switched to password auth, use that password instead.

The shared persistence map lives in Docker VM Runtime.

Infrastructure as Code (Terraform)

For teams preferring infrastructure-as-code workflows, a community-maintained Terraform setup provides:

Modular Terraform configuration with remote state management
Automated provisioning via cloud-init
Deployment scripts (bootstrap, deploy, backup/restore)
Security hardening (firewall, UFW, SSH-only access)
SSH tunnel configuration for gateway access

Repositories:

Infrastructure: fluffbuzz-terraform-hetzner
Docker config: fluffbuzz-docker-config

This approach complements the Docker setup above with reproducible deployments, version-controlled infrastructure, and automated disaster recovery.

Note: Community-maintained. For issues or contributions, see the repository links above.

Next steps

Set up messaging channels: Channels
Configure the Gateway: Gateway configuration
Keep FluffBuzz up to date: Updating

Install overview

Containers

Hosting

Maintenance

Hetzner

FluffBuzz on Hetzner (Docker, Production VPS Guide)

Goal

What are we doing (simple terms)?

Quick path (experienced operators)

What you need

Infrastructure as Code (Terraform)

Next steps

​FluffBuzz on Hetzner (Docker, Production VPS Guide)

​Goal

​What are we doing (simple terms)?

​Quick path (experienced operators)

​What you need

​Infrastructure as Code (Terraform)

​Next steps

FluffBuzz on Hetzner (Docker, Production VPS Guide)

Goal

What are we doing (simple terms)?

Quick path (experienced operators)

What you need

Infrastructure as Code (Terraform)

Next steps