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

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.