Skip to main content
A gateway is a Docker host that runs agents on infrastructure you control. Each gateway is a self-contained runtime environment — agents, browsers, files, and daemons all live inside it. The gateway runs OpenClaw v2026.6.6 as its agent runtime. The gateway has no direct network link to the UI; all coordination happens through Supabase.

​
What’s inside a gateway

A gateway deployment is a set of Docker containers that work together:

Gateway container

Runs OpenClaw (agent runtime), Chrome/Chromium, XFCE desktop, noVNC (remote desktop), and the files API. This is where agents actually execute.

Dispatcher daemon

Subscribes to agent_inbox_items via Supabase Realtime. When new work arrives (task assignments, comment mentions, routines), it wakes the right agent on this gateway. Includes burst-aware batch sizing, inbox deduplication, and backoff for unprovisioned agents to prevent resource exhaustion.

Runner daemon

Subscribes to agent_commands via Supabase Realtime. Leases and executes lifecycle commands: provision, update, remove, provider auth, shell commands, gateway operations. Also runs heartbeat (every 30s) and secrets sync.

Embedder

Runs a local embedding model (default: BAAI/bge-small-en-v1.5). Leases knowledge items pending indexing, generates vector embeddings, and creates chunks. HTTP server at :9100.

File processor

Leases knowledge items with kind='file' and processing_status='ready', downloads from Supabase Storage, extracts text (PDF, DOCX, XLSX, CSV, PPTX, TXT), and triggers embedding.

Shared state volume

Holds OpenClaw config, the local bare git repo with per-agent branches, browser profiles, desktop files, auth tokens, and secrets.

​
How gateways communicate

Gateways are pull-based — they don’t receive inbound connections from the UI. All coordination flows through Supabase:
This means a gateway can run behind NAT, a firewall, or a VPN with no inbound ports open. The only requirement is outbound HTTPS to your Supabase project. The one exception is noVNC: when you open an agent’s remote desktop, the UI proxies WebSocket traffic to the gateway container over Docker’s internal network (or Tailscale, if configured). This is the only direct connection between the UI and the gateway.

​
Gateway lifecycle

​
Boot sequence

When a gateway container starts, entrypoint.sh runs a multi-step boot sequence:
  1. Resolve Supabase credentials (env, token exchange, or workspace registry) 0b. Restore from backup — if no local agent state exists, check Supabase Storage for a previous backup and extract it (restores auth tokens, configs, secrets, Telegram pairing)
  2. Seed the local bare git repo from /opt/templates/ (or $TEMPLATES_SOURCE)
  3. Optionally attach to $GIT_REMOTE_URL for branch backup
  4. Optionally bring up Tailscale ($TAILSCALE_AUTH_KEY)
  5. Run openclaw onboard (first boot only)
  6. Patch openclaw.json with browser, channel, and plugin paths
  7. Install the hq-bootstrap plugin
  8. Start Xtigervnc + XFCE desktop
  9. Start websockify → noVNC
  10. Upsert this gateway’s row in the gateways table with reachable URLs
  11. Exec openclaw gateway start as the main process
On shutdown (SIGTERM), the entrypoint automatically backs up gateway state to Supabase Storage before forwarding the signal to child processes. See Gateway boot for the detailed walkthrough.

​
Heartbeat

The runner daemon writes last_heartbeat_at to the gateways table every 30 seconds. The UI uses this to show gateway health:
  • Healthy (green) — heartbeat within 90 seconds
  • Stale (amber) — status is ready but heartbeat is old
  • No signal — gateway has never reported
If a gateway goes stale, its agents can still have pending work queued — it will be processed when the gateway comes back online.

​
Keepalive (hosted/E2B)

For gateways running in hosted mode (E2B sandboxes), a keepalive daemon maintains the sandbox lifecycle. It performs periodic health checks and renewal requests to prevent the sandbox from being reclaimed. The keepalive supports pause/resume functionality — when no agents are actively running, the keepalive can be paused to reduce overhead, and it automatically resumes when new work arrives.

​
Registration

Gateways register with Supabase via a one-time token exchange. The UI generates a token (Settings → Gateways → Add Gateway), the gateway installer calls consume_gateway_token() to atomically convert the token into a gateways row, and the gateway stores its GATEWAY_ID in .env for all future operations.

​
One workspace, many gateways

A single HQ workspace can have multiple gateways on different hosts — different machines, different data centers, different continents. Each gateway registers itself in the gateways table with its reachable URLs, so the UI knows how to reach each one. Agents are bound to a specific gateway via gateway_id. The dispatcher and runner filter their Supabase subscriptions by GATEWAY_ID — no gateway ever picks up another gateway’s work. Common multi-gateway patterns:
Start with one gateway. You can add more later from Settings → Gateways without reconfiguring anything.

​
Gateway state and persistence

Each gateway owns a Docker volume (gateway-state) that holds:
  • Git repo — a bare repo with one branch per agent. Agent files, skills, memory, and identity all live here.
  • Browser profiles — Chrome profiles persist cookies, logins, and localStorage across agent sessions.
  • Auth tokens — model provider credentials (OpenAI, Anthropic, etc.) stored by OpenClaw.
  • Secrets — decrypted .env files written by the secrets sync daemon (plaintext on disk, chmod 0600).
  • Desktop state — XFCE config, wallpapers, shortcuts.

​
Automatic backup & restore

Since v0.2.1, gateway state is automatically backed up to Supabase Storage on every shutdown and restored on fresh boot. The backup includes auth tokens, agent configs, secrets, and Telegram pairing data. It excludes sessions and codex-home directories to keep backups small. Retention policy: 3 backups per gateway, 7-day max age, newest-first restore with fallback to older backups if the most recent is corrupted. You can also trigger manual backups and view backup status from Settings → Backups in the UI. If you lose the gateway-state volume, the gateway will automatically restore from the most recent backup on next boot — no manual intervention needed. Agents can also be reprovisioned from the database if no backup is available. Use GIT_REMOTE_URL to continuously back up agent branches to GitHub/Gitea for an additional layer of protection. See Operations → Backing up.

​
Adding a gateway

The recommended path is UI-driven:
  1. Settings → Gateways → Add Gateway.
  2. Copy the generated installer command.
  3. Run it on the new host.
See Add a gateway for the full walkthrough, or Networking for how gateways connect.