The blumi gateway (blumi serve) is an always-on local server that lets the blugo phone app and any web browser reach the same blumi coding-agent session over your home or office network. It speaks REST plus Server-Sent Events (SSE) with token authentication, and it advertises itself over mDNS (multicast DNS, service type _blumi._tcp) so the app finds it automatically on the same Wi-Fi. blumi itself is a terminal-first AI coding assistant; the gateway is how you reach that assistant from your phone or browser without anything leaving your LAN (local area network).

• blumi serve runs blumi as an always-on background service for the phone app and browser.
• Default port is 7777; bind it to your machine's LAN IP with --host.
• Discovery is automatic over mDNS (_blumi._tcp) on the same Wi-Fi; no manual IP entry needed.
• Transport is REST + SSE with signed bearer-token auth (7-day TTL).
• A non-loopback bind requires a password — enforced by construction, hashed with argon2.
• Runs as a service: a LaunchAgent on macOS (launchd) or a systemd user unit on Linux, both auto-restarting.
• Nothing is exposed publicly — bind to a trusted LAN interface; never port-forward to the internet.
• blumi gateway is a separate command that runs blumi as a chat bot on Telegram / Discord / Slack / WhatsApp.

The blumi gateway is a local HTTP server you run on your development machine so other devices on your network can drive the same blumi session. The gateway is what the blugo phone app talks to, and it serves a browser UI as well — both reach the identical session that's live in your terminal. It runs as an always-on background service, advertises itself over mDNS for zero-config discovery, and authenticates every client with a token.

blumi serve run # run in the foreground (used by the service + for debugging)
blumi serve pair # set the password; print the LAN URL + token + QR for blugo
blumi serve install # install as a background service (launchd/systemd) + auto-start
blumi serve uninstall # remove the service
blumi serve start # start the installed service
blumi serve stop # stop it
blumi serve status # is it running? URL + pid

Run blumi serve install to register blumi as an auto-starting background service bound to your LAN IP and a port. The full setup is five steps:

1. Find your LAN IP (the address phones can reach):

   • macOS: ipconfig getifaddr en0
   • Linux: hostname -I | awk '{print 1ドル}'

2. Pair — sets a password and prints the connection details (URL + QR):

   blumi serve pair

3. Install as a service bound to your LAN IP + a port (default 7777):

   blumi serve install --host 10.0.0.61 --port 7777

   • macOS → a LaunchAgent ~/Library/LaunchAgents/com.blumi.serve.plist (RunAtLoad + KeepAlive — it restarts on crash and at login).
   • Linux → a systemd user unit ~/.config/systemd/user/blumi-serve.service (Restart=always). For it to run before you log in: loginctl enable-linger $USER.

4. Verify:

   blumi serve status # → running, http://10.0.0.61:7777, pid ...
   curl http://10.0.0.61:7777/api/health # → {"status":"ok"}

5. Connect the app → Mobile App. blugo will list this gateway under "on your network"; tap it and enter the password.

Nothing leaves your network — the gateway is a LAN-only server with mandatory password auth on any non-loopback bind. All traffic stays between your machine and the devices on your Wi-Fi, secrets are never advertised over mDNS, and you should never port-forward the gateway to the public internet.

• A non-loopback bind requires a password (enforced by construction). pair hashes it (argon2) into settings.json; the raw password is never stored.
• Clients authenticate once (/api/login) and reuse a signed bearer token (7-day TTL).
• The mDNS beacon advertises only host/port/name/version + whether auth is required — never a secret.
• Bind to a trusted LAN interface. Don't port-forward the gateway to the public internet.

• Logs: ~/.blumi/serve.log
• Lock file (URL + pid): ~/.blumi/web.lock

blumi serve run --host 10.0.0.61 --port 7777

Runs in the terminal (Ctrl+C to stop) — handy for watching logs while you connect the app.

Distinct from blumi serve (which serves blugo + the browser UI), blumi gateway runs blumi as a chat bot on Telegram / Discord / Slack / WhatsApp. It now has the same service lifecycle as serve:

blumi gateway run # run every configured transport in the foreground
blumi gateway install # install as a background service (launchd/systemd) + auto-start
blumi gateway uninstall # remove the service
blumi gateway start # start it
blumi gateway stop # stop it
blumi gateway status # service state + configured transports

• run / install launch every configured transport at once — a transport counts as configured once its token(s) are set under gateway.*. So set gateway.telegram.token (etc.) first, then blumi gateway install.
• Auto-starts at login and restarts on crash/reboot (launchd KeepAlive / systemd Restart=always), exactly like serve. Service name: com.blumi.gateway (macOS) / blumi-gateway (Linux). Logs: ~/.blumi/gateway.log.
• The single-transport commands (blumi gateway telegram, blumi gateway discord, ...) still run one bot in the foreground — handy for a first test.

⚠ Run only one instance per bot token. Telegram allows a single long-poll consumer, so stop any foreground blumi gateway telegram before installing the service (two at once = repeated 409 Conflict). If a duplicate ever creeps in (e.g. the same token configured on two grid nodes), blumi now logs a loud 409 Conflict warning to ~/.blumi/gateway.log — grep -i conflict ~/.blumi/gateway.log to spot a stray bot — instead of silently double-replying. After a curl ... install.sh upgrade, blumi gateway start (or launchctl kickstart -k gui/$(id -u)/com.blumi.gateway) restarts the service on the new binary.

blumi serve is the LAN server for the blugo phone app and the browser UI (REST + SSE with token auth). blumi gateway is a separate command that runs blumi as a chat bot on Telegram, Discord, Slack, and WhatsApp. They share the same service lifecycle (install / start / stop / status) but serve different clients and use different service names (com.blumi.serve vs com.blumi.gateway).

The default port is 7777. Set a different port with --port, and bind to your machine's LAN IP with --host (for example blumi serve install --host 10.0.0.61 --port 7777).

The gateway advertises itself over mDNS (multicast DNS) under the service type _blumi._tcp, so the blugo app lists it automatically when both devices are on the same Wi-Fi. The mDNS beacon carries only host, port, name, version, and whether auth is required — never a secret. If discovery fails, you can add the gateway manually by IP.

Yes for any non-loopback bind. Binding to a LAN address requires a password by construction; run blumi serve pair to set one. blumi hashes the password with argon2 into settings.json and never stores the raw value. Clients log in once at /api/login and reuse a signed bearer token with a 7-day time-to-live (TTL).

Yes. blumi serve install registers a LaunchAgent on macOS (RunAtLoad + KeepAlive) or a systemd user unit on Linux (Restart=always), so the gateway restarts on crash and at login. On Linux, run loginctl enable-linger $USER to have it start before you log in.

See also: Grid (distributed) to link several gateways, and Troubleshooting.