Skip to main content

Gateway runbook

Use this page for day-1 startup and day-2 operations of the Gateway service.

Deep troubleshooting

Symptom-first diagnostics with exact command ladders and log signatures.

Configuration

Task-oriented setup guide + full configuration reference.

Secrets management

SecretRef contract, runtime snapshot behavior, and migrate/reload operations.

Secrets plan contract

Exact secrets apply target/path rules and ref-only auth-profile behavior.

5-minute local startup

1

Start the Gateway

2

Verify service health

Healthy baseline: Runtime: running and RPC probe: ok.
3

Validate channel readiness

Gateway config reload watches the active config file path (resolved from profile/state defaults, or AGDI_CONFIG_PATH when set). Default mode is gateway.reload.mode="hybrid".

Runtime model

  • One always-on process for routing, control plane, and channel connections.
  • Single multiplexed port for:
    • WebSocket control/RPC
    • HTTP APIs, OpenAI compatible (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • Control UI and hooks
  • Default bind mode: loopback.
  • Auth is required by default (gateway.auth.token / gateway.auth.password, or AGDI_GATEWAY_TOKEN / AGDI_GATEWAY_PASSWORD).

OpenAI-compatible endpoints

Agdi’s highest-leverage compatibility surface is now:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Why this set matters:
  • Most Open WebUI, LobeChat, and LibreChat integrations probe /v1/models first.
  • Many RAG and memory pipelines expect /v1/embeddings.
  • Agent-native clients increasingly prefer /v1/responses.
Planning note:
  • /v1/models is agent-first: it returns agdi, agdi/default, and agdi/<agentId>.
  • agdi/default is the stable alias that always maps to the configured default agent.
  • Use x-agdi-model when you want a backend provider/model override; otherwise the selected agent’s normal model and embedding setup stays in control.
All of these run on the main Gateway port and use the same trusted operator auth boundary as the rest of the Gateway HTTP API.

Port and bind precedence

Hot reload modes

Operator command set

Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.
Then connect clients to ws://127.0.0.1:18789 locally.
If gateway auth is configured, clients still must send auth (token/password) even over SSH tunnels.
See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

Use supervised runs for production-like reliability.
LaunchAgent labels are ai.agdi.gateway (default) or ai.agdi.<profile> (named profile). agdi doctor audits and repairs service config drift.

Multiple gateways on one host

Most setups should run one Gateway. Use multiple only for strict isolation/redundancy (for example a rescue profile). Checklist per instance:
  • Unique gateway.port
  • Unique AGDI_CONFIG_PATH
  • Unique AGDI_STATE_DIR
  • Unique agents.defaults.workspace
Example:
See: Multiple gateways.

Dev profile quick path

Defaults include isolated state/config and base gateway port 19001.

Protocol quick reference (operator view)

  • First client frame must be connect.
  • Gateway returns hello-ok snapshot (presence, health, stateVersion, uptimeMs, limits/policy).
  • Requests: req(method, params) → res(ok/payload|error).
  • Common events: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
Agent runs are two-stage:
  1. Immediate accepted ack (status:"accepted")
  2. Final completion response (status:"ok"|"error"), with streamed agent events in between.
See full protocol docs: Gateway Protocol.

Operational checks

Liveness

  • Open WS and send connect.
  • Expect hello-ok response with snapshot.

Readiness

Gap recovery

Events are not replayed. On sequence gaps, refresh state (health, system-presence) before continuing.

Common failure signatures

For full diagnosis ladders, use Gateway Troubleshooting.

Safety guarantees

  • Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
  • Invalid/non-connect first frames are rejected and closed.
  • Graceful shutdown emits shutdown event before socket close.

Related: