Skip to main content

​
Multiple Gateways (same host)

Most setups should use one Gateway because a single Gateway can handle multiple messaging connections and agents. If you need stronger isolation or redundancy (e.g., a rescue bot), run separate Gateways with isolated profiles/ports. For most users, the simplest rescue-bot setup is:
  • keep the main bot on the default profile
  • run the rescue bot on --profile rescue
  • use a completely separate Telegram bot for the rescue account
  • keep the rescue bot on a different base port such as 19789
This keeps the rescue bot isolated from the main bot so it can debug or apply config changes if the primary bot is down. Leave at least 20 ports between base ports so the derived browser/canvas/CDP ports never collide.

​
Rescue-Bot Quickstart

Use this as the default path unless you have a strong reason to do something else: 
# Rescue bot (separate Telegram bot, separate profile, port 19789)
fluffbuzz --profile rescue onboard
fluffbuzz --profile rescue gateway install --port 19789
If your main bot is already running, that is usually all you need. During fluffbuzz --profile rescue onboard:
  • use the separate Telegram bot token
  • keep the rescue profile
  • use a base port at least 20 higher than the main bot
  • accept the default rescue workspace unless you already manage one yourself
If onboarding already installed the rescue service for you, the final gateway install is not needed.

​
Why This Works

The rescue bot stays independent because it has its own:
  • profile/config
  • state directory
  • workspace
  • base port (plus derived ports)
  • Telegram bot token
For most setups, use a completely separate Telegram bot for the rescue profile:
  • easy to keep operator-only
  • separate bot token and identity
  • independent from the main bot’s channel/app install
  • simple DM-based recovery path when the main bot is broken

​
What --profile rescue onboard Changes

fluffbuzz --profile rescue onboard uses the normal onboarding flow, but it writes everything into a separate profile. In practice, that means the rescue bot gets its own:
  • config file
  • state directory
  • workspace (by default ~/.fluffbuzz/workspace-rescue)
  • managed service name
The prompts are otherwise the same as normal onboarding.

​
General Multi-Gateway Setup

The rescue-bot layout above is the easiest default, but the same isolation pattern works for any pair or group of Gateways on one host. For a more general setup, give each extra Gateway its own named profile and its own base port: 
# main (default profile)
fluffbuzz setup
fluffbuzz gateway --port 18789

# extra gateway
fluffbuzz --profile ops setup
fluffbuzz --profile ops gateway --port 19789
If you want both Gateways to use named profiles, that also works: 
fluffbuzz --profile main setup
fluffbuzz --profile main gateway --port 18789

fluffbuzz --profile ops setup
fluffbuzz --profile ops gateway --port 19789
Services follow the same pattern: 
fluffbuzz gateway install
fluffbuzz --profile ops gateway install --port 19789
Use the rescue-bot quickstart when you want a fallback operator lane. Use the general profile pattern when you want multiple long-lived Gateways for different channels, tenants, workspaces, or operational roles.

​
Isolation Checklist

Keep these unique per Gateway instance:
  • FLUFFBUZZ_CONFIG_PATH — per-instance config file
  • FLUFFBUZZ_STATE_DIR — per-instance sessions, creds, caches
  • agents.defaults.workspace — per-instance workspace root
  • gateway.port (or --port) — unique per instance
  • derived browser/canvas/CDP ports
If these are shared, you will hit config races and port conflicts.

​
Port mapping (derived)

Base port = gateway.port (or FLUFFBUZZ_GATEWAY_PORT / --port).
  • browser control service port = base + 2 (loopback only)
  • canvas host is served on the Gateway HTTP server (same port as gateway.port)
  • Browser profile CDP ports auto-allocate from browser.controlPort + 9 .. + 108
If you override any of these in config or env, you must keep them unique per instance.

​
Browser/CDP notes (common footgun)

  • Do not pin browser.cdpUrl to the same values on multiple instances.
  • Each instance needs its own browser control port and CDP range (derived from its gateway port).
  • If you need explicit CDP ports, set browser.profiles.<name>.cdpPort per instance.
  • Remote Chrome: use browser.profiles.<name>.cdpUrl (per profile, per instance).

​
Manual env example

FLUFFBUZZ_CONFIG_PATH=~/.fluffbuzz/main.json \
FLUFFBUZZ_STATE_DIR=~/.fluffbuzz \
fluffbuzz gateway --port 18789

FLUFFBUZZ_CONFIG_PATH=~/.fluffbuzz/rescue.json \
FLUFFBUZZ_STATE_DIR=~/.fluffbuzz-rescue \
fluffbuzz gateway --port 19789

​
Quick checks

fluffbuzz gateway status --deep
fluffbuzz --profile rescue gateway status --deep
fluffbuzz --profile rescue gateway probe
fluffbuzz status
fluffbuzz --profile rescue status
fluffbuzz --profile rescue browser status
Interpretation:
  • gateway status --deep helps catch stale launchd/systemd/schtasks services from older installs.
  • gateway probe warning text such as multiple reachable gateways detected is expected only when you intentionally run more than one isolated gateway.