Protocol

OpenViber’s runtime has three components that communicate:

1. Viber runtime (daemon) — runs on the user’s machine, executes AI tasks.
2. Gateway — central coordinator that routes messages between Viber runtimes and the web app.
3. Web App (Viber Board) — SvelteKit frontend that operators use to interact with tasks.

Terminology note: in this doc, “daemon” refers to the Viber runtime process. “Gateway” is the central coordinator (started with viber gateway). This is distinct from the Channels server (viber channels, enterprise channel webhooks) and the Skill Hub (src/skills/hub/).

The protocol is intentionally simple. The AI SDK handles the complex parts (streaming, tool calls, message formatting). OpenViber’s protocol is just the plumbing that connects them.

1. Architecture

┌──────────┐   HTTP/SSE   ┌──────────┐   WebSocket   ┌──────────┐    AI SDK    ┌─────┐
│ Browser  │ ←──────────→ │ Web App  │ ←───────────→ │ Gateway  │ ←──────────→ │Daemon│
│ (Svelte) │              │(SvelteKit)│               │ (Node)   │              │(Node)│
└──────────┘              └──────────┘               └──────────┘              └──────┘
  @ai-sdk/svelte            API routes                REST + WS             streamText()
  Chat class               gateway                  task routing         toUIMessageStream

Transport Summary

2. Gateway REST API

The gateway exposes a REST API for the web app (via src/gateway/):

SSE Stream Endpoint

GET /api/tasks/:id/stream holds the connection open and relays AI SDK SSE bytes from the daemon. Key headers:

Content-Type: text/event-stream
x-vercel-ai-ui-message-stream: v1

The stream closes when the task completes, errors, or is stopped.

3. Gateway ↔ Viber Runtime (Daemon) WebSocket Protocol

Viber runtimes (daemons) connect outbound to the gateway at ws://{gateway}/ws with auth headers:

Authorization: Bearer {token}
X-Viber-Id: {viberId}
X-Viber-Version: {version}

Viber Runtime → Gateway Messages

Gateway → Viber Runtime Messages

ViberInfo Shape

interface ViberInfo {
  id: string;
  name: string;
  version: string;
  platform: string;
  capabilities: string[];
  runningTasks: string[];
  skills?: ViberSkillInfo[];
}

interface ViberSkillInfo {
  id: string;
  name: string;
  description: string;
  available: boolean;
  status: "AVAILABLE" | "NOT_AVAILABLE" | "UNKNOWN";
  healthSummary?: string;
}

interface ConfigState {
  configVersion: string;       // hash of current config
  lastConfigPullAt: string;    // ISO timestamp
  validations: ConfigValidation[];
}

interface ConfigValidation {
  category: "llm_keys" | "oauth" | "env_secrets" | "skills" | "binary_deps";
  status: "verified" | "failed" | "unchecked";
  message?: string;
  checkedAt: string;
}

4. Task States

Tasks have a simple lifecycle:

pending → running → completed
                  → error
                  → stopped

5. Message Injection Modes

When an operator sends a follow-up message during a running task, the injectionMode controls behavior:

6. Terminal Streaming

Terminal I/O uses the same WebSocket connection between Viber runtime (daemon) and gateway, with a dedicated message namespace (terminal:*). The gateway relays terminal data to the web app via a separate WebSocket connection on port 6008 (not through the SSE stream).

7. Security

• Outbound-only: Viber runtimes (daemons) connect outbound to the gateway. No inbound ports needed.
• Auth headers: WebSocket connections include Authorization and X-Viber-Id headers.
• CORS: Gateway sets Access-Control-Allow-Origin: * for development (should be restricted in production).
• No secrets in stream: The SSE stream contains only AI response content, never API keys or credentials.

8. Design Decisions