gateway

Gateway CLI

The Gateway is Agdi’s WebSocket server (channels, nodes, sessions, hooks).

Subcommands in this page live under agdi gateway ….

Related docs:

• /gateway/bonjour
• /gateway/discovery
• /gateway/configuration

Run the Gateway

Run a local Gateway process:

agdi gateway

Foreground alias:

agdi gateway run

Notes:

• By default, the Gateway refuses to start unless gateway.mode=local is set in ~/.agdi/agdi.json. Use --allow-unconfigured for ad-hoc/dev runs.
• Binding beyond loopback without auth is blocked (safety guardrail).
• SIGUSR1 triggers an in-process restart when authorized (commands.restart is enabled by default; set commands.restart: false to block manual restart, while gateway tool/config apply/update remain allowed).
• SIGINT/SIGTERM handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.

Options

• --port <port>: WebSocket port (default comes from config/env; usually 18789).
• --bind <loopback|lan|tailnet|auto|custom>: listener bind mode.
• --auth <token|password>: auth mode override.
• --token <token>: token override (also sets OPENCLAW_GATEWAY_TOKEN for the process).
• --password <password>: password override. Warning: inline passwords can be exposed in local process listings.
• --password-file <path>: read the gateway password from a file.
• --tailscale <off|serve|funnel>: expose the Gateway via Tailscale.
• --tailscale-reset-on-exit: reset Tailscale serve/funnel config on shutdown.
• --allow-unconfigured: allow gateway start without gateway.mode=local in config.
• --dev: create a dev config + workspace if missing (skips BOOTSTRAP.md).
• --reset: reset dev config + credentials + sessions + workspace (requires --dev).
• --force: kill any existing listener on the selected port before starting.
• --verbose: verbose logs.
• --claude-cli-logs: only show claude-cli logs in the console (and enable its stdout/stderr).
• --ws-log <auto|full|compact>: websocket log style (default auto).
• --compact: alias for --ws-log compact.
• --raw-stream: log raw model stream events to jsonl.
• --raw-stream-path <path>: raw stream jsonl path.

Query a running Gateway

All query commands use WebSocket RPC.

Output modes:

• Default: human-readable (colored in TTY).
• --json: machine-readable JSON (no styling/spinner).
• --no-color (or NO_COLOR=1): disable ANSI while keeping human layout.

Shared options (where supported):

• --url <url>: Gateway WebSocket URL.
• --token <token>: Gateway token.
• --password <password>: Gateway password.
• --timeout <ms>: timeout/budget (varies per command).
• --expect-final: wait for a “final” response (agent calls).

Note: when you set --url, the CLI does not fall back to config or environment credentials. Pass --token or --password explicitly. Missing explicit credentials is an error.

gateway health

agdi gateway health --url ws://127.0.0.1:18789

gateway status

gateway status shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.

agdi gateway status
agdi gateway status --json
agdi gateway status --require-rpc

Options:

• --url <url>: override the probe URL.
• --token <token>: token auth for the probe.
• --password <password>: password auth for the probe.
• --timeout <ms>: probe timeout (default 10000).
• --no-probe: skip the RPC probe (service-only view).
• --deep: scan system-level services too.
• --require-rpc: exit non-zero when the RPC probe fails. Cannot be combined with --no-probe.

Notes:

• gateway status resolves configured auth SecretRefs for probe auth when possible.
• If a required auth SecretRef is unresolved in this command path, gateway status --json reports rpc.authWarning when probe connectivity/auth fails; pass --token/--password explicitly or resolve the secret source first.
• If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
• Use --require-rpc in scripts and automation when a listening service is not enough and you need the Gateway RPC itself to be healthy.
• On Linux systemd installs, service auth drift checks read both Environment= and EnvironmentFile= values from the unit (including %h, quoted paths, multiple files, and optional - files).

gateway probe

gateway probe is the “debug everything” command. It always probes:

• your configured remote gateway (if set), and
• localhost (loopback) even if remote is configured.

If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.

agdi gateway probe
agdi gateway probe --json

Interpretation:

• Reachable: yes means at least one target accepted a WebSocket connect.
• RPC: ok means detail RPC calls (health/status/system-presence/config.get) also succeeded.
• RPC: limited - missing scope: operator.read means connect succeeded but detail RPC is scope-limited. This is reported as degraded reachability, not full failure.
• Exit code is non-zero only when no probed target is reachable.

JSON notes (--json):

• Top level:
  • ok: at least one target is reachable.
  • degraded: at least one target had scope-limited detail RPC.
• Per target (targets[].connect):
  • ok: reachability after connect + degraded classification.
  • rpcOk: full detail RPC success.
  • scopeLimited: detail RPC failed due to missing operator scope.

Remote over SSH (Mac app parity)

The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at ws://127.0.0.1:<port>.

CLI equivalent:

agdi gateway probe --ssh user@gateway-host

Options:

• --ssh <target>: user@host or user@host:port (port defaults to 22).
• --ssh-identity <path>: identity file.
• --ssh-auto: pick the first discovered gateway host as SSH target (LAN/WAB only).

Config (optional, used as defaults):

• gateway.remote.sshTarget
• gateway.remote.sshIdentity

gateway call <method>

Low-level RPC helper.

agdi gateway call status
agdi gateway call logs.tail --params '{"sinceMs": 60000}'

Manage the Gateway service

agdi gateway install
agdi gateway start
agdi gateway stop
agdi gateway restart
agdi gateway uninstall

Notes:

• gateway install supports --port, --runtime, --token, --force, --json.
• When token auth requires a token and gateway.auth.token is SecretRef-managed, gateway install validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
• If token auth requires a token and the configured token SecretRef is unresolved, install fails closed instead of persisting fallback plaintext.
• For password auth on gateway run, prefer OPENCLAW_GATEWAY_PASSWORD, --password-file, or a SecretRef-backed gateway.auth.password over inline --password.
• In inferred auth mode, shell-only OPENCLAW_GATEWAY_PASSWORD does not relax install token requirements; use durable config (gateway.auth.password or config env) when installing a managed service.
• If both gateway.auth.token and gateway.auth.password are configured and gateway.auth.mode is unset, install is blocked until mode is set explicitly.
• Lifecycle commands accept --json for scripting.

Discover gateways (Bonjour)

gateway discover scans for Gateway beacons (_agdi-gw._tcp).

• Multicast DNS-SD: local.
• Unicast DNS-SD (Wide-Area Bonjour): choose a domain (example: agdi.internal.) and set up split DNS + a DNS server; see /gateway/bonjour

Only gateways with Bonjour discovery enabled (default) advertise the beacon.

Wide-Area discovery records include (TXT):

• role (gateway role hint)
• transport (transport hint, e.g. gateway)
• gatewayPort (WebSocket port, usually 18789)
• sshPort (SSH port; defaults to 22 if not present)
• tailnetDns (MagicDNS hostname, when available)
• gatewayTls / gatewayTlsSha256 (TLS enabled + cert fingerprint)
• cliPath (optional hint for remote installs)

gateway discover

agdi gateway discover

Options:

• --timeout <ms>: per-command timeout (browse/resolve); default 2000.
• --json: machine-readable output (also disables styling/spinner).

Examples:

agdi gateway discover --timeout 4000
agdi gateway discover --json | jq '.beacons[].wsUrl'