Gateway Architecture

The Gateway is the core of the Koi — a single long-lived daemon that runs as a systemd service on the dedicated EC2 instance. It owns the WebSocket control plane and handles all message routing.

How It Runs

On each SkyKoi EC2 instance:

• •The agent runtime is installed globally via npm
• •The Gateway runs as a systemd-managed service
• •It listens on localhost:18789
• •nginx reverse proxies port 443 (self-signed TLS) → localhost:18789
• •The frontend connects via WSS (WebSocket Secure) on port 443
• •Authentication uses token-based auth (gateway.auth.mode: "token")

WebSocket Protocol

The wire protocol uses text frames with JSON payloads:

// Client request
{ "type": "req", "id": "abc123", "method": "agent", "params": { "message": "Hello" } }

// Server response
{ "type": "res", "id": "abc123", "ok": true, "payload": { "runId": "run_1", "status": "accepted" } }

// Server-push event
{ "type": "event", "event": "agent", "payload": { "runId": "run_1", "status": "streaming", "text": "..." } }

Connection Lifecycle

Client                    Gateway
  |                          |
  |---- req:connect -------->|  (auth token + device identity)
  |<------ res (ok) ---------|  (hello-ok: presence + health snapshot)
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|  (send a message to the agent)
  |<------ res:agent --------|  (ack: runId + status:"accepted")
  |<------ event:agent ------|  (streaming response)
  |<------ res:agent --------|  (final: runId + status + summary)

Key Configuration

The Gateway reads JSON5 config from /home/ubuntu/.skykoi/skykoi.json. Key settings configured by SkyKoi:

• •gateway.mode — Set to "local" (single-user mode)
• •gateway.auth.mode — "token" for token-based authentication
• •agents.defaults — Workspace path (/home/ubuntu/koi), model (amazon-bedrock/us.anthropic.claude-opus-4-6-v1)
• •exec.security — "full" (unrestricted shell access)
• •exec.host — "gateway" (commands run directly on the EC2 instance)
• •session — DM scope, reset policy, idle timeout