> ## Documentation Index
> Fetch the complete documentation index at: https://beige.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```mermaid theme={null}
graph TB
    subgraph "Gateway Process"
        AM[Agent Manager]
        SM[Sandbox Manager]
        SS[Socket Server]
        PE[Policy Engine]
        AL[Audit Logger]
        API[HTTP API :7433]
        PL[Plugin System]
    end

    subgraph "Docker Sandboxes"
        SB1[Agent 1]
        SB2[Agent 2]
    end

    subgraph "Channels"
        TUI[TUI Process]
        HTTP[HTTP Client]
        PLUG_CH[Plugin Channels]
    end

    AM --> SM
    SM --> SB1
    SM --> SB2
    SB1 -->|Unix socket| SS
    SB2 -->|Unix socket| SS
    SS --> PE
    PE --> AL

    TUI -->|HTTP :7433| API
    HTTP -->|HTTP :7433| API
    PLUG_CH --> PL
    API --> AM
    PL --> AM
```

***

## 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](/agents/configuration) for the full configuration schema.

***

## In This Section

<CardGroup cols={2}>
  <Card icon="arrow-right-arrow-left" href="/gateway/tool-calls" title="How Tool Calls Work">
    What happens from the moment the LLM calls a tool to when the result comes back
  </Card>

  <Card icon="play" href="/gateway/operating" title="Operating the Gateway">
    Starting, stopping, monitoring, and troubleshooting the gateway process
  </Card>
</CardGroup>