Gateway
The AgentOS gateway is the local server behind the Web UI, channels, RPC clients, sessions, approvals, diagnostics, and usage views. Most day-to-day AgentOS 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:
agentos 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:
agentos gateway start --json
Inspect it:
agentos gateway status
agentos gateway status --json
Restart or stop it:
agentos gateway restart
agentos 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:
agentos gateway run --port 18792
agentos gateway status --port 18792
Bind to a specific host:
agentos 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:
agentos 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:
agentos gateway run --config /path/to/agentos.toml
agentos gateway status --config /path/to/agentos.toml
AgentOS also reads standard configuration locations described in
configuration.md.
Remote Status Check
Inspect a gateway URL directly:
agentos 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.
agentos gateway restart
Troubleshooting
Check status and readiness:
agentos gateway status
agentos doctor
If the port is busy:
agentos gateway run --port 18792
If the Web UI cannot connect, confirm that the URL matches the gateway bind host and port.
Read next: