Web / WebSocket

Web Channel

Human provides a WebSocket-based channel for web UIs and browser extensions. Supports local mode (direct WebSocket to the gateway) and relay mode (connect through a relay server).

Prerequisites

• Build with -DHU_ENABLE_WEB=ON or -DHU_ENABLE_ALL_CHANNELS=ON
• Gateway running for WebSocket connections
• Web UI or browser extension that implements the WebChannel v1 protocol

Configuration

Local mode

For development or local use, bind to loopback:

{
  "channels": {
    "web": {
      "accounts": {
        "default": {
          "transport": "local",
          "listen": "127.0.0.1",
          "port": 32123,
          "path": "/ws",
          "auth_token": "replace-with-long-random-token",
          "allowed_origins": [
            "http://localhost:5173",
            "chrome-extension://your-extension-id"
          ]
        }
      }
    }
  }
}

Relay mode

For remote access, use the relay transport:

{
  "channels": {
    "web": {
      "accounts": {
        "default": {
          "transport": "relay",
          "relay_url": "wss://relay.human.io/ws/agent",
          "relay_agent_id": "default",
          "relay_token": "replace-with-relay-token",
          "relay_token_ttl_secs": 2592000,
          "relay_pairing_code_ttl_secs": 300,
          "relay_ui_token_ttl_secs": 86400,
          "relay_e2e_required": false
        }
      }
    }
  }
}

Fields

Field	Type	Description
transport	string	"local" or "relay"
listen	string	Bind address (127.0.0.1 local, 0.0.0.0 for remote)
port	number	WebSocket port
path	string	WebSocket path (e.g. /ws)
auth_token	string	Optional; required when binding non-loopback
allowed_origins	array	CORS origins for WebSocket upgrade
relay_url	string	Relay server WebSocket URL (relay mode)
relay_agent_id	string	Agent identifier on the relay
relay_token	string	Token for relay authentication
relay_token_ttl_secs	number	TTL for relay token
relay_pairing_code_ttl_secs	number	Pairing code expiry
relay_ui_token_ttl_secs	number	UI JWT TTL
relay_e2e_required	bool	Require E2E encryption for relay payloads

How it works

Pairing flow

1. Client sends pairing_request with one-time pairing_code
2. Server responds with pairing_result including access_token (JWT)
3. Client includes access_token in every user_message (top-level or payload.access_token)

Events

• assistant_chunk: Streaming text chunks
• assistant_final: Final assistant message
• Event envelope format: {"v":1,"type":"assistant_chunk"|"assistant_final","session_id":"...","agent_id":"default","payload":{"content":"..."}}

Local vs relay

• Local: WebSocket server runs in the gateway; UI connects directly to ws://127.0.0.1:port/path
• Relay: Agent connects outbound to relay; UI connects to relay separately; relay routes messages

E2E (relay)

When relay_e2e_required is true, the UI and agent exchange X25519 keys during pairing and send encrypted payloads in payload.e2e.

Platform limitations

• Gateway required: Web channel needs the gateway for WebSocket serving
• Token validation: Optional auth_token validates WebSocket upgrade when binding non-loopback
• Protocol: See spec/webchannel_v1.json for the full WebChannel v1 specification
• UI/extension separate: The web UI or Chrome extension lives in a separate repository and connects via the WebSocket endpoint