Gateway runbook

Use this page for day-1 startup and day-2 operations of the Gateway service.

📌

Deep troubleshooting

Symptom-first diagnostics with exact command ladders and log signatures.

📌

Configuration

Task-oriented setup guide + full configuration reference.

5-minute local startup

Start the Gateway

bash
mayros gateway --port 18789
# debug/trace mirrored to stdio
mayros gateway --port 18789 --verbose
# force-kill listener on selected port, then start
mayros gateway --force

Verify service health

bash
mayros gateway status
mayros status
mayros logs --follow

Healthy baseline: Runtime: running and RPC probe: ok.

Validate channel readiness

bash
mayros channels status --probe

Gateway config reload watches the active config file path (resolved from profile/state defaults, or MAYROS_CONFIG_PATH when set). Default mode is gateway.reload.mode="hybrid".

Runtime model

One always-on process for routing, control plane, and channel connections.
Single multiplexed port for:
- WebSocket control/RPC
- HTTP APIs (OpenAI-compatible, Responses, tools invoke)
- Control UI and hooks
Default bind mode: loopback.
Auth is required by default (gateway.auth.token / gateway.auth.password, or MAYROS_GATEWAY_TOKEN / MAYROS_GATEWAY_PASSWORD).

Port and bind precedence

Setting	Resolution order
Gateway port	`--port` → `MAYROS_GATEWAY_PORT` → `gateway.port` → `18789`
Bind mode	CLI/override → `gateway.bind` → `loopback`

Hot reload modes

`gateway.reload.mode`	Behavior
`off`	No config reload
`hot`	Apply only hot-safe changes
`restart`	Restart on reload-required changes
`hybrid` (default)	Hot-apply when safe, restart when required

Operator command set

bash
mayros gateway status
mayros gateway status --deep
mayros gateway status --json
mayros gateway install
mayros gateway restart
mayros gateway stop
mayros logs --follow
mayros doctor

Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.

bash
ssh -N -L 18789:127.0.0.1:18789 user@host

Then connect clients to ws://127.0.0.1:18789 locally.

If gateway auth is configured, clients still must send auth (token/password) even over SSH tunnels.

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

Use supervised runs for production-like reliability.

bash
mayros gateway install
mayros gateway status
mayros gateway restart
mayros gateway stop

LaunchAgent labels are ai.mayros.gateway (default) or ai.mayros.<profile> (named profile). mayros doctor audits and repairs service config drift.

Multiple gateways on one host

Most setups should run one Gateway. Use multiple only for strict isolation/redundancy (for example a rescue profile).

Checklist per instance:

Unique gateway.port
Unique MAYROS_CONFIG_PATH
Unique MAYROS_STATE_DIR
Unique agents.defaults.workspace

Example:

bash
MAYROS_CONFIG_PATH=~/.mayros/a.json MAYROS_STATE_DIR=~/.mayros-a mayros gateway --port 19001
MAYROS_CONFIG_PATH=~/.mayros/b.json MAYROS_STATE_DIR=~/.mayros-b mayros gateway --port 19002

See: Multiple gateways.

Dev profile quick path

bash
mayros --dev setup
mayros --dev gateway --allow-unconfigured
mayros --dev status

Defaults include isolated state/config and base gateway port 19001.

Protocol quick reference (operator view)

First client frame must be connect.
Gateway returns hello-ok snapshot (presence, health, stateVersion, uptimeMs, limits/policy).
Requests: req(method, params) → res(ok/payload|error).
Common events: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Agent runs are two-stage:

Immediate accepted ack (status:"accepted")
Final completion response (status:"ok"|"error"), with streamed agent events in between.

See full protocol docs: Gateway Protocol.

Operational checks

Liveness

Open WS and send connect.
Expect hello-ok response with snapshot.

Readiness

bash
mayros gateway status
mayros channels status --probe
mayros health

Gap recovery

Events are not replayed. On sequence gaps, refresh state (health, system-presence) before continuing.

Common failure signatures

Signature	Likely issue
`refusing to bind gateway ... without auth`	Non-loopback bind without token/password
`another gateway instance is already listening` / `EADDRINUSE`	Port conflict
`Gateway start blocked: set gateway.mode=local`	Config set to remote mode
`unauthorized` during connect	Auth mismatch between client and gateway

For full diagnosis ladders, use Gateway Troubleshooting.

Safety guarantees

Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
Invalid/non-connect first frames are rejected and closed.
Graceful shutdown emits shutdown event before socket close.