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. Ctrl+C and SIGTERM (what
agentos gateway stop, the desktop app, launchd and systemd send) run the
same orderly shutdown: new turns are refused, turns in flight get up to 30
seconds to finish, channels stop, connected clients receive a shutdown
event, sockets and MCP clients close, and the process exits 0. A second
signal cancels the turns still running instead of waiting for them.
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.
agentos gateway status --json also reports what a supervisor needs from a
live gateway: drain_budget_ms (how long a stop may take to drain turns),
active_turns (turns running right now) and runtime — the gateway's own
readiness state (starting, ready, draining, safe_mode), what is
failing, and the safe_mode details. The top-level state stays the
process state (running, unmanaged, not_started, ...). Add --deep to
also report an installed service.
Run as a Service
Keep the gateway running across crashes, logouts and reboots by installing it as a user service:
agentos gateway install # port from config (usually 18791)
agentos gateway install --port 18792 --config ~/.agentos/config.toml
agentos gateway status --deep # adds the service: installed, loaded/active
agentos gateway uninstall
| Platform | Unit | Restart policy |
|---|---|---|
| macOS | LaunchAgent ~/Library/LaunchAgents/dev.useagentos.gateway.plist (label dev.useagentos.gateway), logs in ~/Library/Logs/AgentOS/gateway-service.log and gateway-service.err.log | KeepAlive, RunAtLoad, ThrottleInterval 10 (at most one respawn per 10 s), ExitTimeOut 54 |
| Linux | systemd user unit ~/.config/systemd/user/agentos-gateway.service (systemctl --user daemon-reload + enable --now) | Restart=always, RestartSec=5, RestartPreventExitStatus=78, KillMode=mixed, TimeoutStopSec=54 |
| Windows | not supported | — |
The unit runs the absolute path of the agentos you installed it with
(~/.local/bin/agentos keeps working after uv tool upgrade) as
agentos gateway run --port N [--config PATH], with a PATH that starts with
~/.local/bin, /opt/homebrew/bin and /usr/local/bin, followed by the
installing shell's own PATH, so harness CLIs installed with Homebrew, npm,
nvm, volta, bun or pyenv are found. AGENTOS_STATE_DIR and
AGENTOS_GATEWAY_CONFIG_PATH are carried into the unit when they are set in
the installing shell, and AGENTOS_SERVICE (launchd or systemd) tells
the gateway it runs under a service manager. The stop timeout (54 s) is the
gateway's worst-case stop — 30 s for turns to finish, 2 s to cancel the rest,
2 s for clients' closing handshakes and 10 s for the HTTP server to stop —
plus a 10 s margin, derived from the bounds the shutdown itself uses.
Installing the same unit again is a no-op, also from a shell whose PATH
differs (the installed unit is kept; uninstall and install again to refresh
its PATH). A different unit under the same name (another port or config, or
a job with that label loaded from elsewhere) is refused: run
agentos gateway uninstall first. --no-start writes the unit without
loading it. uninstall with nothing installed succeeds. On Linux, run
loginctl enable-linger $USER once if the gateway should keep running after
you log out.
agentos gateway stop does not stop a service-run gateway: the service
manager would start it again. It exits 3 and says how to stop it instead —
launchctl bootout gui/$(id -u)/dev.useagentos.gateway until the next login
on macOS, systemctl --user stop agentos-gateway.service on Linux — or remove
the service with agentos gateway uninstall. agentos gateway restart
restarts a service-run gateway in place.
A configuration error (exit 78) is not restarted by systemd. launchd has no
such switch and would respawn it every 10 s, so under launchd the gateway
waits before exiting 78: 5 s, doubling with each consecutive config failure
up to 5 minutes (a streak older than 15 minutes starts over, a successful
boot resets it), and says so in ~/Library/Logs/AgentOS/gateway-service.log.
The desktop app adopts a gateway that already answers on its port, so it works with an installed service; do not let both start their own gateway on the same state directory.
Crash-loop breaker (safe mode)
Every boot is recorded in the gateway database, with a heartbeat every 30 s. When a boot finds 3 unclean boots that ended in the last 5 minutes — runs that ended without a clean shutdown (killed, crashed, out of memory), counted by their last heartbeat, so a gateway that ran for an hour before crashing counts as crashing now — it starts in safe mode instead of restarting the same crash forever:
- the control plane starts as usual: Web UI, WebSocket, HTTP,
agentos doctor, logs, config; - channels, the cron scheduler and the heartbeat are held back, so no automatic turn runs;
/readyanswers200withstate: "safe_mode"and the reason, andagentos doctorreports agateway.safe_modefinding with the way out;- safe mode clears by itself once the 5-minute window drains without another unclean boot (checked every 30 s), and everything it held back starts then.
To leave it sooner, fix the cause (the log has the crash) and run
agentos channels start --yes: it starts every channel, the scheduler and the
heartbeat, and stops counting the recorded crashes. agentos channels start NAME --yes starts a single channel and keeps safe mode on for the rest — the
way to find which channel crashes the gateway.
A clean stop never counts: agentos gateway stop, a service manager's or the
desktop app's SIGTERM, Ctrl+C and an in-place restart are all clean. Nor
does a boot that failed before it served (a bad config, a failed migration):
safe mode could not help it. If the boot ledger cannot be read the breaker is
skipped for that boot (fail open), never the start.
Supervisor Contract
What a process supervisor (the desktop app, launchd, systemd, a script) can rely on:
| Signal | Contract |
|---|---|
GET /health | Liveness: 200 whenever the HTTP server answers. |
GET /ready | {ready, state, failing, startup, safe_mode, drain_budget_ms, uptime_ms}. state is starting (boot sidecars still running; failing names them, e.g. ["channels"]), ready, draining (stopping or restarting in place; failing: ["draining"]) or safe_mode (failing: ["safe_mode"]). 503 while starting or draining; 200 for ready and safe_mode, where the control plane serves so the cause can be fixed. In ready and safe_mode, failing also names each channel that is down (failed to start, or stopped on bad credentials) as channel:<name>; that does not make the gateway unready. startup.failed.channels records which channels failed at boot and why. turn_recovery counts the interrupted turns found at boot by state (found, pending, running, resumed, closed, tombstoned, cancelled, reported, expired) plus auto_resume; it never makes the gateway unready. |
GET /startupz | 200 once every boot sidecar settled (channels started, router preloaded), 503 before; pending lists what is left. |
WebSocket connect during boot | Answered with a retryable error UNAVAILABLE, details: {code: "STARTUP_SIDECARS", retry_after_ms}, then close 1013 (gateway starting). Clients retry after retry_after_ms; the CLI retries for up to 30 s, the web console and desktop keep "connecting". |
shutdown event | {reason, restart_expected_ms}, flushed to every connection before its socket closes with 1012. A number is an in-place restart with an estimate of when the gateway serves again (this boot's own duration plus teardown, at least 3 s); null is a terminal stop (a signal, Ctrl+C). A client that stopped reading may still miss it (each flush is bounded to 1 s); on close 1012 without the frame, reconnect with the normal backoff. |
Exit code 78 | EX_CONFIG: a startup failure only a configuration change fixes — a config file that is not valid TOML or does not validate, a schema migration that cannot apply, a public bind without auth. Repair, then retry; systemd's RestartPreventExitStatus=78 stops a restart loop. Other startup failures exit 1. |
The desktop app follows it: a spawned gateway is "running" once /ready
answers 200; on exit 78 it runs agentos doctor --json once, retries the
start once, and otherwise shows the exit code with doctor's top finding.
Sleep and wake
A laptop gateway checks itself every 30 s. A gap of more than 45 s between two
checks during which the process used almost no CPU means the machine slept:
the gateway logs gateway.thaw, restarts the channels that are idle (their
sockets are stale after a sleep), wakes the scheduler and tells connected
clients to refresh (health event). Every 5 minutes (after a 60 s start-up
grace) it also sweeps channel health and restarts a channel that is
disconnected, stuck (its retry loop gave up), start_failed (its last
start raised, e.g. no network at login) or stale-socket (no inbound event
for 30 minutes on a socket or polling transport), at most once per two sweeps
each.
A restart that fails — the network is not back yet right after a wake — never
leaves the channel stopped: the gateway retries the start with backoff
(1 s, 2 s, 4 s, ... six times; the channel reads retrying), and if that
runs out the channel reads stuck and the next sweep starts over. Only a
channel that failed on bad credentials (terminal) or that the platform
blocked is never restarted automatically: doctor reports it with the fix.
A channel you stopped yourself (agentos channels logout) stays stopped.
agentos channels status shows each channel's state and the reason it is
down, and whether safe mode is on; --json adds last_event_at,
terminal_reason, start_error, and the policy plus the last sweep and thaw
(restarted, failed, skipped per channel) under health_policy.
Host and Port
Use a different port:
agentos gateway run --port 18792
agentos gateway status --port 18792
Pick where the gateway listens with a bind mode:
| Mode | Listens on | Notes |
|---|---|---|
loopback | 127.0.0.1 | The default. Only this machine can connect. |
lan | 0.0.0.0 (every interface) | Token auth is required; the gateway refuses to start without it. |
tailnet | the Tailscale IPv4 and 127.0.0.1 | Reads the address from tailscale ip -4. Fails to start if Tailscale is missing, stopped or logged out — it never falls back to 0.0.0.0. Token auth is required. |
custom | the host you configured | What --listen / --bind select. |
agentos gateway run --bind-mode tailnet
agentos gateway start --bind-mode lan
Or persist it:
[gateway]
bind = "tailnet"
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; either one means bind mode custom. gateway start records the
bind mode it used, so a plain gateway status, gateway stop or gateway restart finds that gateway again (--bind-mode is accepted there too). On
macOS the Tailscale app's bundled CLI is used when tailscale is not on PATH. Precedence, highest first:
--listen, --bind, --bind-mode, AGENTOS_LISTEN, AGENTOS_GATEWAY_HOST,
[gateway] bind, the host key, 127.0.0.1.
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 --bind-mode lan --port 18791
Do not expose a gateway to an untrusted network without token auth and a network
boundary you understand. To reach a gateway from another machine, prefer
keeping it on loopback and tunnelling in (SSH, Tailscale Serve) or putting an
authenticating reverse proxy in front: see Remote Access.
agentos doctor flags risky exposure settings.
Browser origins
Every bind applies the same origin policy to the WebSocket handshake, to
/api/* requests that carry an Origin header, and to CORS. A browser page may
drive the gateway when its origin is:
- listed in
control_ui.allowed_origins,cors.allowed_originsor[gateway] public_origin, or is the gateway's ownhttp://localhost:<port>/http://127.0.0.1:<port>(always allowed, so a LAN bind never locks out the browser on the gateway's machine); - the same origin as the address the request was sent to, when that address is
private: loopback,
10/8,172.16/12,192.168/16, link-local,100.64.0.0/10(tailnet addresses), IPv6fc00::/7, or a.local/.ts.netname. Openinghttp://192.168.1.20:18791/control/on a LAN bind works with no configuration; - a loopback origin on another port (a dev server) when the connection itself comes from this machine and not through a proxy.
Anything else is refused with 403 — for a WebSocket, at the handshake, before
the upgrade — and CORS never answers *. On a loopback bind only loopback addresses count for
rule 2. Requests without an Origin header — the CLI, curl, scripts — are not
affected; token auth still applies.
The Host header is checked too (a DNS-rebinding guard): the gateway answers to
loopback, to the hostnames of the declared origins, and off loopback to any IP
address and .local / .ts.net names. A request for any other name gets 400
naming the setting to change.
When you serve the console from a public address or a DNS name, declare the origin you open it at:
[gateway]
public_origin = "https://agent.example.com"
Without it, the gateway refuses to start the Control UI on a specific public
address (it would load and then fail every request). The fix is in the error
message; control_ui.enabled = false keeps the API running without the console.
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.
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
That works for a gateway started with agentos gateway start (stop, then
start) and for one started any other way — the desktop app, launchd, systemd
or a terminal agentos gateway run — which restarts itself in place: the
gateway drains the turns in flight, re-executes itself under the same process
id so every launcher keeps tracking it, and comes back on upgraded code. The
CLI confirms the restart from the gateway's readiness probe. Not available on
Windows, where the process image cannot be replaced.
The same in-place restart is reachable from chat:
/restartin the web console or the desktop app (operators only, no setting needed). The socket drops and reconnects; a toast reports when the gateway is back./restartfrom a paired Telegram, Discord or Slack sender, and the agent's owngatewaytool, once[gateway_control] chat_restart = trueis set and the gateway has been restarted once. The reply acknowledges, then "Gateway restarted (v…, Ns)" lands in the same chat or thread after boot.
/restart waits up to 30 seconds for active turns to finish; /restart force
(or agentos gateway restart --force) cancels them instead. A second
request while one is pending is reported, not queued.
Interrupted turns
A turn the gateway stops under -- a restart that cancels it, or a crash --
is marked interrupted (task status abandoned, reason
shutdown_interrupted or process_restart). On the next boot, once channels
are up, the gateway looks at every session whose newest turn is such a turn
and decides from the transcript what to do:
- The reply (or an error) was already written, or there is nothing to answer: nothing to resume.
- The user's message was never answered, or the last recorded tool round finished: the turn is resumed with the session's usual tools.
- Tool calls were issued with no recorded result (their outcome is unknown):
the turn is resumed with read and status tools only (file, git, memory
and session reads,
web_search), so it checks what happened instead of acting again. Shell, file writes, trading, outbound messages, approvals and arbitrary HTTP are not available to that turn; the user's next message gets every tool back.
The resume is a short internal continuation message, not a replay of the
user's message, and its reply goes where a normal reply would: the web
console and the desktop app show it in the session, a channel turn's reply is
sent to the same chat or thread. A turn from a paired channel is resumed only
while that sender's pairing still stands. Each interrupted turn gets at most
three attempts (counted across restarts, with backoff); after that, or for a
turn older than 24 hours, the session gets a note asking the user to send a
message to continue. A new message on the session cancels a resume that has
not started yet. Cron, heartbeat, subagent and ACP turns are never resumed,
and neither is anything while the gateway is in safe mode. A turn that asked
for the restart itself (the gateway tool's restart, or a shell command
that restarts, stops or updates the gateway), or any turn of the session the
restart request came from, is not resumed either, so it cannot restart the
gateway again: its session gets a note instead.
[task_runtime] resume_interrupted_turns = false turns the automatic resume
off: interrupted turns are only reported (the note in the session, /ready
turn_recovery, an agentos doctor finding).
[task_runtime]
resume_interrupted_turns = true # default
Troubleshooting
Check status and readiness:
agentos gateway status
agentos doctor
curl -s http://127.0.0.1:18791/ready
If /ready reports state: "safe_mode", the gateway restarted after crashing
three times in five minutes and is holding channels, cron and heartbeat back;
see Crash-loop breaker.
If agentos gateway run exits 78, the configuration is the problem: run
agentos doctor and fix what it reports before starting again.
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: