Skip to content

gateway.md

Latest commit

 

History

History
156 lines (106 loc) · 3.58 KB

gateway.md

File metadata and controls

156 lines (106 loc) · 3.58 KB
Raw

Gateway

The OpenSquilla gateway is the local server behind the Web UI, channels, RPC clients, sessions, approvals, diagnostics, and usage views. Most day-to-day OpenSquilla surfaces work best when the gateway is running.

Use this page when you want to start, stop, inspect, expose, or troubleshoot the gateway.

Foreground Gateway

Run the gateway in the current terminal:

opensquilla gateway run

Open the control console:

http://127.0.0.1:18791/control/

Stop a foreground gateway with Ctrl+C.

Managed Background Gateway

Start a managed background process and wait for readiness:

opensquilla gateway start --json

Inspect it:

opensquilla gateway status
opensquilla gateway status --json

Restart or stop it:

opensquilla gateway restart
opensquilla gateway stop

Stop and restart shut down gracefully: in-flight agent turns and background completions are drained before the process exits, and the force-kill deadline exceeds that drain budget so work is not cut off mid-write. Tune the per-phase drain budget with OPENSQUILLA_GATEWAY_GRACEFUL_TIMEOUT (seconds; default 30, bounded). The same drain runs on Ctrl+C / SIGTERM for a foreground gateway. On Windows — which has no real SIGTERM — the desktop app and gateway stop trigger the drain through an owner-only, loopback POST /api/system/shutdown.

Use the managed gateway for the Web UI, channels, scheduled jobs, and local automation that should survive the current terminal tab.

Host and Port

Use a different port:

opensquilla gateway run --port 18792
opensquilla gateway status --port 18792

Bind to a specific host:

opensquilla gateway run --listen 127.0.0.1 --port 18791

--listen is an alias for the bind host and wins over --bind when both are provided.

Safety Defaults

The gateway defaults to loopback scope, usually 127.0.0.1, because the local gateway controls chat, tools, sessions, channels, approvals, and configuration.

Public binding is opt-in:

opensquilla gateway run --listen 0.0.0.0 --port 18791

Do not expose a gateway to an untrusted network without token auth and a network boundary you understand.

Configuration Path

Use a specific config file:

opensquilla gateway run --config /path/to/opensquilla.toml
opensquilla gateway status --config /path/to/opensquilla.toml

OpenSquilla also reads standard configuration locations described in configuration.md.

Remote Status Check

Inspect a gateway URL directly:

opensquilla gateway status --gateway ws://localhost:18791/ws

This is useful when a client or MCP bridge is configured with an explicit gateway URL.

When to Restart

Restart the gateway after changing:

  • provider or router configuration;
  • channel configuration;
  • durable agent entries;
  • global sandbox posture;
  • search or image-generation setup;
  • environment variables used by configured providers.
opensquilla gateway restart

Troubleshooting

Check status and readiness:

opensquilla gateway status
opensquilla doctor

If the port is busy:

opensquilla gateway run --port 18792

If the Web UI cannot connect, confirm that the URL matches the gateway bind host and port.

Read next:

Docs index · Product guide · Improve this page · Report a docs issue