#Gateway Settings

The gateway is the collaboration hub. It manages sessions, adapters (like Discord), and the Control Core UI.

#Minimal config

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "fsRoots": ["."],
    "auth": { "mode": "none" },
    "controlUi": {
      "enabled": true,
      "port": 18790,
      "pairingRequired": true,
      "allowInsecureAuth": false
    },
    "dynamicUiEnabled": true
  }
}

#Auth modes

Set gateway.auth.mode to one of:

• none (default)
• token
• password

You can also provide a token via env var:

export WINGMAN_GATEWAY_TOKEN="..."

#Token placement (explicit)

Recommended (do not store token in JSON):

1. Set config auth mode:

{
  "gateway": {
    "auth": { "mode": "token" }
  }
}

2. Provide token at runtime:

export WINGMAN_GATEWAY_TOKEN="your-token"

Fallback (less secure):

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-token"
    }
  }
}

#CLI control

wingman gateway start
wingman gateway start --discovery mdns --name "Home Gateway"
wingman gateway status
wingman gateway stop

#Node enablement and revocation

Node execution is explicitly device-gated. A connected client is not a node until it is approved.

• Enable/disable a device with PUT /api/nodes/:clientId
• Revoke with DELETE /api/nodes/:clientId
• Inspect all node approvals + live node connections with GET /api/nodes

Example:

# Enable this desktop device as a node
curl -X PUT http://127.0.0.1:18789/api/nodes/desktop-abc123 \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"name":"Wingman Desktop"}'

# Revoke later
curl -X DELETE http://127.0.0.1:18789/api/nodes/desktop-abc123

Desktop app flow:

• User connects to gateway
• User toggles Enable this device as a node
• App registers as a node and can service req:node invocations (system.notify, system.run)
• Agents can invoke these capabilities via node_notify and node_run tools

Note:

• Changing Node Name while node mode is already enabled updates the active node name on the next registration event (toggle node mode or reconnect).

#Cloudflare deployment

Use the dedicated Cloudflare app at apps/cloudflare to run Wingman Gateway on Cloudflare Workers + Containers.

cd apps/cloudflare
bun install
bun run dev
# or
bun run deploy

This deployment proxies all HTTP/WebSocket traffic to a containerized gateway process started with:

wingman gateway run --host 0.0.0.0 --port 8080

Before exposing publicly, switch gateway auth from none to token and set WINGMAN_GATEWAY_TOKEN.

Additional utilities:

wingman gateway token --generate
wingman gateway discover --verbose
wingman gateway join ws://host:port/ws --name="node-1"

#File system roots

fsRoots defines which directories are allowed when selecting a session working folder (workdir) in the Control UI/API.

• The selected workdir must be inside one of these roots.
• When set, the session workdir becomes the agent's active execution root (tool CWD + file backend root) for subsequent turns in that session.
• Keep this list tight to reduce risk.

#Control UI media and uploads

The Control UI chat supports file uploads in addition to existing media capture, and it renders streamed assistant media attachments when models return structured image/audio/file blocks:

• Media in: image uploads, pasted screenshots, and audio/voice attachments
• Media out: streamed assistant image/audio/file attachments from model output blocks
• Text/code files: .txt, .md, .csv, .json, .yaml, .yml, .xml, .log, .ts, .js, .py, .go, .rs, .java, .c, .cpp, .sql, .html, .css
• PDF: .pdf uploads use provider-native PDF handling when supported, with text-extraction fallback

If local PDF text extraction fails, Wingman still sends a fallback note so the request continues without breaking.

#State directory

Set gateway.stateDir to control where persistent data is stored (sessions, routines). If omitted, Wingman uses .wingman/.

#Dynamic UI

Use gateway.dynamicUiEnabled to enable or disable SGUI rendering in the Control UI. See the Dynamic UI (SGUI) guide for registry, tools, and examples.

#MCP proxy wrapper

Use gateway.mcpProxy to wrap stdio MCP servers with a proxy runtime (for tracing/guardrails pipelines).

{
  "gateway": {
    "mcpProxy": {
      "enabled": false,
      "command": "uvx",
      "baseArgs": ["invariant-gateway@latest", "mcp"],
      "projectName": "wingman-gateway",
      "pushExplorer": false,
      "apiKey": "optional-key",
      "apiUrl": "optional-url"
    }
  }
}

Behavior notes:

• When disabled (enabled: false), MCP servers run exactly as configured.
• When enabled, Wingman rewrites stdio MCP process launches to execute through the proxy command.
• Wingman checks for uv only when this feature is enabled and the proxy command is uv/uvx.
• If uv is missing in this mode, gateway startup fails with an error (no interactive prompt).