Skip to main content
The gateway is the central server process that connects every channel, runs agents, and serves the Control UI. All inbound messages from WhatsApp, Telegram, Slack, Discord, Signal, iMessage, and voice arrive here before being routed to the appropriate agent session. 
bun genosos.mjs gateway
On first launch, the onboarding wizard runs, prompts for an API key, and opens the browser automatically.

​
Access

InterfaceURL / CommandNotes
Control UIhttp://127.0.0.1:18789Binds to loopback only by default
TUIbun genosos.mjs tuiWebSocket connection to the running gateway
canvas-hosthttp://127.0.0.1:18793Visual workspace (canvas tools)
The gateway refuses to start on a public interface without authentication configured. Do not expose port 18789 directly to the internet. Use SSH tunneling or Tailscale instead.

​
Remote access

To reach the gateway from another device, keep it on loopback and forward access through a secure tunnel. SSH tunnel (recommended for one-off access) 
# From your remote device
ssh -L 18789:127.0.0.1:18789 user@gateway-host
Then open http://127.0.0.1:18789 locally. Tailscale Serve (persistent, on-network access) 
tailscale serve 18789
Tailscale Funnel (expose to the internet — use with caution) 
tailscale funnel 18789

​
Startup sequence

When bun genosos.mjs gateway runs, the gateway initializes in 17 steps:
1

CLI routing → gateway handler

The entry point (genosos.mjs) parses the command and dispatches to the gateway handler in src/gateway/server.impl.js.
2

Load .env + validate Bun runtime

Environment variables are loaded via dotenv. The Bun runtime version is checked against the >=1.2.0 requirement.
3

Harden state directory permissions

~/.genosv1/ directory permissions are tightened (owner read/write only). Spotlight and Time Machine metadata exclusions are applied.
4

Init audit log (Fortress Mode)

The tamper-evident audit log is initialized with HMAC checksums. If Fortress Mode is enabled, full hardening activates here.
5

Build Control UI assets

The Lit 3 + Vite 7 Control UI assets in ui/ are built if needed and served from dist/control-ui/.
6

Load + validate genosos.json

~/.genosv1/genosos.json is loaded and validated against the Zod schema. A 200ms TTL cache is initialized.
7

Load channel extensions

All 29 active channel extensions are loaded from extensions/. Each extension declares its own dependencies.
8

Init subagent registry

The subagent registry is initialized. Existing agent UUIDs from ~/.genosv1/agents/ are registered.
9

Load model catalog

The static model catalog (src/agents/static-model-catalog.json) is loaded, then combined with any discovered models from configured providers.
10

Build cron service

The cron scheduler (croner) is initialized with any scheduled tasks defined in agent workspaces.
11

Warm memory search manager

The dual-backend memory system (QMD + SQLite with sqlite-vec) is warmed. This prefetches index data and takes approximately 150ms on first run.
12

Create channel manager → start all channels

Each configured and enabled channel is started in parallel. Channels authenticate, connect to their respective services, and become ready to receive messages.
13

Attach WebSocket handlers

WebSocket handlers (ws 8.19.0) are attached to the HTTP server for real-time communication with the Control UI and TUI.
14

Listen on port 18789

The Express + HTTP server begins accepting connections on 127.0.0.1:18789 (or the configured bind address).
15

Run onboarding wizard (first run)

On the first launch, the onboarding wizard runs: it prompts for a provider selection (Anthropic, OpenAI, or Gemini), collects the API key, and opens the browser.
16

Start mDNS/Bonjour discovery

The gateway advertises itself on the local network via mDNS/Bonjour (using @homebridge/ciao). Other GenosOS devices on the same network can discover the gateway automatically.
17

Start maintenance timers

Background timers start for heartbeat pings (per-agent health checks) and skill cache refresh.

​
Configuration

The gateway is configured through the gateway.* config section. The recommended way is through conversation: 
"Show me the gateway configuration"
"Change the gateway port to 19000"
Or directly with genosos config: 
genosos config get gateway.port
genosos config set gateway.bind loopback
Key settings:
PathDefaultDescription
gateway.port18789TCP port the server listens on
gateway.bindloopbackBind address: loopback, lan, or explicit IP
gateway.auth—Authentication mode for the Control UI

​
Scheduled tasks (cron)

The gateway includes a cron scheduler (croner) that runs tasks on a schedule defined in agent workspaces. Tasks are delivered to the agent via chat.send, so the agent sees them as regular messages and responds using its full tool set. Manage cron from the agent: 
"Run a security audit every day at 9am"
"Check my calendar every morning"
"Remind me to review the analytics every Monday"

​
Ports used

PortService
18789Gateway (HTTP + WebSocket)
18793canvas-host (visual workspace)
Both ports bind to 127.0.0.1 by default.