---
summary: "Loopback WebChat static host and Gateway WS usage for chat UI"
read_when:
- Debugging or configuring WebChat access
title: "WebChat"
---
# WebChat (Gateway WebSocket UI)
Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.
## What it is
- A native chat UI for the gateway (no embedded browser and no local static server).
- Uses the same sessions and routing rules as other channels.
- Deterministic routing: replies always go back to WebChat.
## Quick start
1. Start the gateway.
2. Open the WebChat UI (macOS/iOS app) or the Control UI chat tab.
3. Ensure gateway auth is configured (required by default, even on loopback).
## How it works (behavior)
- The UI connects to the Gateway WebSocket and uses `chat.history` , `chat.send` , and `chat.inject` .
- `chat.history` is bounded for stability: Gateway may truncate long text fields, omit heavy metadata, and replace oversized entries with `[chat.history omitted: message too large]` .
- `chat.inject` appends an assistant note directly to the transcript and broadcasts it to the UI (no agent run).
- Aborted runs can keep partial assistant output visible in the UI.
- Gateway persists aborted partial assistant text into transcript history when buffered output exists, and marks those entries with abort metadata.
- History is always fetched from the gateway (no local file watching).
- If the gateway is unreachable, WebChat is read-only.
## Control UI agents tools panel
- The Control UI `/agents` Tools panel fetches a runtime catalog via `tools.catalog` and labels each
tool as `core` or `plugin:<id>` (plus `optional` for optional plugin tools).
- If `tools.catalog` is unavailable, the panel falls back to a built-in static list.
- The panel edits profile and override config, but effective runtime access still follows policy
precedence (`allow`/`deny`, per-agent and provider/channel overrides).
## Remote use
- Remote mode tunnels the gateway WebSocket over SSH/Tailscale.
- You do not need to run a separate WebChat server.
## Configuration reference (WebChat)
Full configuration: [Configuration ](/gateway/configuration )
Channel options:
- No dedicated `webchat.*` block. WebChat uses the gateway endpoint + auth settings below.
Related global options:
- `gateway.port` , `gateway.bind` : WebSocket host/port.
- `gateway.auth.mode` , `gateway.auth.token` , `gateway.auth.password` : WebSocket auth (token/password).
- `gateway.auth.mode: "trusted-proxy"` : reverse-proxy auth for browser clients (see [Trusted Proxy Auth ](/gateway/trusted-proxy-auth )).
- `gateway.remote.url` , `gateway.remote.token` , `gateway.remote.password` : remote gateway target.
- `session.*` : session storage and main key defaults.