The Gateway

The central process that orchestrates agents, sandboxes, policies, and channels

The gateway is the heart of Beige — a single long-running Node.js process that coordinates everything: agent lifecycle, Docker sandbox management, tool routing, policy enforcement, and audit logging.

Every agent runs inside a Docker sandbox that the gateway creates and owns. Every tool call an agent makes passes through the gateway before anything executes. The gateway is always the single source of truth.

---

Core Responsibilities

Component	What it does
Agent Manager	Owns the mapping of agent name → LLM session + Docker sandbox
Sandbox Manager	Creates and tears down Docker containers; generates tool launcher scripts at startup
Socket Server	Listens on a Unix socket per agent; receives tool requests from inside the sandbox
Policy Engine	Checks every tool invocation against the agent’s allowed-tools list before it runs
Audit Logger	Appends a structured JSONL record for every tool call — tool, args, timing, decision
HTTP API	REST endpoints on port 7433 for TUI and external integrations
Plugin System	Loads plugins that provide tools, channels, hooks, and skills

---

Configuration and Storage

The gateway reads its configuration from ~/.beige/config.json5 on startup. Key runtime files:

Path	Purpose
~/.beige/config.json5	Main configuration file
~/.beige/gateway.pid	PID of the running gateway process
~/.beige/logs/gateway.log	Gateway log output
~/.beige/sessions/<agent>/	Persisted conversation sessions
~/.beige/workspaces/<agent>/	Agent workspace (bind-mounted into sandbox)
~/.beige/provider-health.json	LLM provider cooldown state

See the Config Reference for the full configuration schema.

---

In This Section

How Tool Calls Work

What happens from the moment the LLM calls a tool to when the result comes back

Operating the Gateway

Starting, stopping, monitoring, and troubleshooting the gateway process