BEEOS CLOUD / DEVELOPER REFERENCE

Canvas relay and terminal bridge

WebSocket helpers for the canvas relay and the terminal bridge.

Both clients build the authentication handshake and frames; the actual socket can be injected. Yjs payload bytes and terminal bytes stay with the harness.

CanvasRelayClient

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

Owns the relay upgrade, auth headers, and join/leave frames. Yjs payload bytes stay with the harness.

class CanvasRelayClient
new CanvasRelayClient(readonly options: CanvasRelayClientOptions)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`options`	CanvasRelayClientOptions	yes		`relayUrl` and the harness `keys`, plus optional `agentId`, `token` and `socketFactory` (replaces the real WebSocket, for example in tests).

Python · Constructor

Parameter	Type	Required	Default	Description
`relay_url`	`str`	yes		URL of the canvas relay, as returned together with the canvas token.
`keys`	AgentKeyPair	yes		The harness key pair that signs the request.
`agent_id`	`str \| None`	no	`None`	Optional identifier of the agent; added to the URL as `agentId`.
`token`	`str \| None`	no	`None`	Optional canvas token; added to the URL as `token`.
`socket_factory`	Callable[[str, dict[str, str]], CanvasRelaySocket] \| None	no	`None`	Optional function `(url, headers)` that creates the socket instead of the real WebSocket; useful in tests.

connect

Opens the WebSocket with the signed upgrade headers. Resolves when it is open and rejects on a connection error.

connect(onMessage?: (data: Uint8Array | string) => void): Promise<void>

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`onMessage`	`(data: Uint8Array \| string) => void`	no		Called with each incoming frame: text as a string, binary as bytes.

Returns Promise<void>

Python · Parameters

No parameters.

Returns None

join

Sends the frame that joins a canvas. Throws when not connected.

join(canvasId: string): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`canvasId`	`string`	yes		Identifier of the canvas.

Returns void

Python · Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`str`	yes		Identifier of the canvas.

Returns None

leave

Sends the frame that leaves a canvas. Throws when not connected.

leave(canvasId: string): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`canvasId`	`string`	yes		Identifier of the canvas.

Returns void

Python · Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`str`	yes		Identifier of the canvas.

Returns None

sendBinary / send_binary

Sends a binary frame for a canvas: one byte with the length of the canvas id, the canvas id, then the payload. Throws when not connected.

sendBinary(canvasId: string, payload: Uint8Array): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`canvasId`	`string`	yes		Identifier of the canvas.
`payload`	`Uint8Array`	yes		Bytes to send after the canvas id.

Returns void

Python · Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`str`	yes		Identifier of the canvas.
`payload`	`bytes`	yes		Bytes to send after the canvas id.

Returns None

close

Closes the socket.

close(): void

TypeScript · Parameters

No parameters.

Returns void

Python · Parameters

No parameters.

Returns None

CanvasRelaySocket

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

The part of a WebSocket that the canvas relay client uses. Implement it to supply your own socket, for example in tests.

interface CanvasRelaySocket

send

Sends a text or binary frame.

send(data: string | Uint8Array): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`data`	`string \| Uint8Array`	yes		Frame content.

Returns void

Python · Parameters

Parameter	Type	Required	Default	Description
`data`	`str \| bytes`	yes		Frame content.

Returns None

close

Closes the socket.

close(): void

TypeScript · Parameters

No parameters.

Returns void

Python · Parameters

No parameters.

Returns None

on

TypeScript only

Registers a listener for open, message or error.

on(event: "error", listener: (error: Error) => void): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`event`	`"error"`	yes		Event name: `open`, `message` or `error`.
`listener`	`(error: Error) => void`	yes		Callback invoked with the event payload.

Returns void

wait_open

Python only

Waits until the socket is open.

async def wait_open() -> None

Python · Parameters

No parameters.

Returns None

TerminalBridgeClient

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

Opens GET /agent and sends the lease-bound agent_auth frame. Later frames are raw terminal bytes.

class TerminalBridgeClient
new TerminalBridgeClient(readonly options: TerminalBridgeClientOptions)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`options`	TerminalBridgeClientOptions	yes		`bridgeUrl`, the harness `keys` and the runtime `lease`, plus optional `now`, `nonce`, `authTimeoutMs` (default 10000) and `socketFactory`.

Python · Constructor

Parameter	Type	Required	Default	Description
`bridge_url`	`str`	yes		`ws` or `wss` URL of the terminal bridge.
`keys`	AgentKeyPair	yes		The harness key pair that signs the request.
`lease`	TerminalAuthLease	yes		The runtime lease that the authentication frame is bound to.
`now`	`Callable[[], float] \| None`	no	`None`	Optional clock that returns the current time; replace it in tests.
`nonce`	`Callable[[], str] \| None`	no	`None`	Optional nonce generator; replace it in tests.
`socket_factory`	Callable[[str], TerminalSocket] \| None	no	`None`	Optional function that creates the socket for a URL instead of the real WebSocket; useful in tests.

connect

Opens the socket, sends the agent_auth frame and waits for auth_ok. Returns the frame that was sent; fails when the answer is anything else or does not arrive within the timeout.

async connect(): Promise<TerminalAgentAuthFrame>

TypeScript · Parameters

No parameters.

Returns Promise<TerminalAgentAuthFrame>

Python · Parameters

No parameters.

Returns dict[str, Any]

send

Sends terminal data. Throws when not connected.

send(data: string): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`data`	`string`	yes		Terminal data to send.

Returns void

Python · Parameters

Parameter	Type	Required	Default	Description
`data`	`str`	yes		Terminal data to send.

Returns None

close

Closes the socket.

close(): void

TypeScript · Parameters

No parameters.

Returns void

Python · Parameters

No parameters.

Returns None

TerminalSocket

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

The part of a WebSocket that the terminal bridge client uses. Implement it to supply your own socket, for example in tests.

interface TerminalSocket

send

Sends a text frame.

send(data: string): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`data`	`string`	yes		Frame content.

Returns void

Python · Parameters

Parameter	Type	Required	Default	Description
`data`	`str`	yes		Frame content.

Returns None

close

Closes the socket.

close(): void

TypeScript · Parameters

No parameters.

Returns void

Python · Parameters

No parameters.

Returns None

on

TypeScript only

Registers a listener for message or error.

on(event: "error", listener: (error: Error) => void): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`event`	`"error"`	yes		Event name: `message` or `error`.
`listener`	`(error: Error) => void`	yes		Callback invoked with the event payload.

Returns void

once

TypeScript only

Registers a listener that is called once, for the open event.

once(event: "open", listener: () => void): void

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`event`	`"open"`	yes		Event name: `open`.
`listener`	`() => void`	yes		Callback invoked when the socket is open.

Returns void

wait_open

Python only

Waits until the socket is open.

async def wait_open() -> None

Python · Parameters

No parameters.

Returns None

recv

Python only

Waits for the next text frame and returns it.

async def recv() -> str

Python · Parameters

No parameters.

Returns str

canvasRelayJoinFrame

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

Returns the text frame that joins a canvas: {"type":"join","canvasId":...}.

function canvasRelayJoinFrame(canvasId: string): string

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`canvasId`	`string`	yes		Identifier of the canvas.

Returns string

Python · Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`str`	yes		Identifier of the canvas.

Returns str

canvasRelayLeaveFrame

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

Returns the text frame that leaves a canvas: {"type":"leave","canvasId":...}.

function canvasRelayLeaveFrame(canvasId: string): string

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`canvasId`	`string`	yes		Identifier of the canvas.

Returns string

Python · Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`str`	yes		Identifier of the canvas.

Returns str

canvasRelayUpgradeHeaders

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

Builds the signed X-Agent-* headers for the relay WebSocket upgrade (GET /ws/agent).

function canvasRelayUpgradeHeaders(keys: AgentKeyPair): Record<string, string>

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`keys`	AgentKeyPair	yes		The harness key pair that signs the request.

Returns Record<string, string>

Python · Parameters

Parameter	Type	Required	Default	Description
`keys`	AgentKeyPair	yes		The harness key pair that signs the request.

Returns dict[str, str]

canvasRelayWebSocketUrl

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

{relay}/ws/agent. An existing path prefix is kept. Never /ws/{canvasId}.

function canvasRelayWebSocketUrl(relayUrl: string, options: { agentId?: string; token?: string } = {}): string

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`relayUrl`	`string`	yes		URL of the canvas relay. `http(s)` becomes `ws(s)`; a missing scheme becomes `wss`.
`options`	`{ agentId?: string; token?: string }`	no	`{}`	Optional `agentId` and `token`; they are added as query parameters.

Returns string

Python · Parameters

Parameter	Type	Required	Default	Description
`relay_url`	`str`	yes		URL of the canvas relay. `http(s)` becomes `ws(s)`; a missing scheme becomes `wss`.
`agent_id`	`str \| None`	no	`None`	Optional identifier of the agent; added as the query parameter `agentId`.
`token`	`str \| None`	no	`None`	Optional canvas token; added as the query parameter `token`.

Returns str

createTerminalAgentAuth

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

Builds and signs the agent_auth frame for the terminal bridge. Throws when the lease is incomplete, the epoch is not a positive integer string, or the public key is not 32 bytes.

function createTerminalAgentAuth(input: { lease: TerminalAuthLease; keys: AgentKeyPair; timestamp?: number; nonce?: string; }): TerminalAgentAuthFrame

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	{ lease: TerminalAuthLease; keys: AgentKeyPair; timestamp?: number; nonce?: string; }	yes		The runtime `lease`, the harness `keys`, and optionally a `timestamp` in Unix seconds and a `nonce`.

Returns TerminalAgentAuthFrame

Python · Parameters

Parameter	Type	Required	Default	Description
`lease`	TerminalAuthLease	yes		The runtime lease that the frame is bound to.
`keys`	AgentKeyPair	yes		The harness key pair that signs the request.
`timestamp`	`int \| None`	no	`None`	Time in Unix seconds; defaults to now.
`nonce`	`str \| None`	no	`None`	Nonce; a random UUID by default.

Returns dict[str, Any]

encodeCanvasRelayBinary

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

Builds the binary relay frame: one byte with the length of the canvas id, the canvas id, then the payload. The canvas id must be 1 to 255 bytes long.

function encodeCanvasRelayBinary(canvasId: string, payload: Uint8Array): Uint8Array

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`canvasId`	`string`	yes		Identifier of the canvas.
`payload`	`Uint8Array`	yes		Bytes to send after the canvas id.

Returns Uint8Array

Python · Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`str`	yes		Identifier of the canvas.
`payload`	`bytes`	yes		Bytes to send after the canvas id.

Returns bytes

terminalAgentAuthSigningMessage

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

UTF-8 preimage. instance_id is not included.

function terminalAgentAuthSigningMessage(input: { publicKey: string; timestamp: number; nonce: string; runtimeLeaseCredential: string; handlerIdentity: string; runtimeEpoch: string; leaseId: string; }): string

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	`{ publicKey: string; timestamp: number; nonce: string; runtimeLeaseCredential: string; handlerIdentity: string; runtimeEpoch: string; leaseId: string; }`	yes		The fields that are signed: `publicKey`, `timestamp`, `nonce` and the lease fields `runtimeLeaseCredential`, `handlerIdentity`, `runtimeEpoch` and `leaseId`.

Returns string

Python · Parameters

Parameter	Type	Required	Description
`public_key`	`str`	yes	Base64 public key of the harness.
`timestamp`	`int`	yes	Time in Unix seconds.
`nonce`	`str`	yes	Nonce of the frame.
`runtime_lease_credential`	`str`	yes	Lease credential of the runtime lease.
`handler_identity`	`str`	yes	Handler identity of the runtime lease.
`runtime_epoch`	`str`	yes	Runtime epoch of the lease.
`lease_id`	`str`	yes	Identifier of the lease.

Returns str

terminalAgentWebSocketUrl

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

Returns the terminal bridge WebSocket URL: the bridge URL with /agent appended. Throws unless the scheme is ws or wss.

function terminalAgentWebSocketUrl(bridgeUrl: string): string

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`bridgeUrl`	`string`	yes		`ws` or `wss` URL of the terminal bridge.

Returns string

Python · Parameters

Parameter	Type	Required	Default	Description
`bridge_url`	`str`	yes		`ws` or `wss` URL of the terminal bridge.

Returns str

CANVAS_RELAY_PATH

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

Path of the relay WebSocket: /ws/agent.

const CANVAS_RELAY_PATH: "/ws/agent" = "/ws/agent"

BeeOS CloudBack to documentation