The relay

A browser cannot listen on or dial a raw TCP or QUIC connection. The relay is a small WebSocket service that carries a browser’s CapTP bytes to a peer that can open a socket.

The relay only moves bytes

The CapTP handshake (op:start-session) and every message after it run between the browser and the far peer. On a cleartext path the relay can read or alter them, so use noise-relay when the relay must see only ciphertext. The Zig provider, the other language providers, and the browser connector all support noise-relay.

Reaching the other side

The relay either dials a peer or connects to one registered with it.

Dialing a far peer

The browser names a target and the relay dials it. The Deno reference relay reads the target off the WebSocket’s query: ?to=host:port opens a TCP socket, and ?locator=<ocapn-uri> opens an iroh channel. The relay forwards bytes between the WebSocket and that connection. Rooms runs the same forwarding behind its own /relay route.

On the iroh path, the relay terminates QUIC and can read the CapTP bytes. The browser trusts it to dial the named node and report the verified key. WSS protects the browser-to-relay leg. It does not hide traffic from the relay. Use noise-relay to a peer registered under that transport when the relay must not read or alter the session.

The browser names the peer it wants. The relay dials it over tcp or iroh and pipes the two together. The keyed session runs end to end, and the relay only moves bytes.

The app that hosts the relay sets the dial policy. Rooms pins its TCP target to its directory, so a TCP dial reaches the directory and nothing else. An iroh target may be any node that proves its key, so the app caps connections itself.

When both ends are browsers

Neither browser can be dialed, so one registers its key with the relay and leaves an inbound socket held there. A second browser, holding an introduction that names that key, dials it, and the relay bridges the dialer to the held socket. The room that made the introduction carries no part of the session (ADR-0034).

One browser registers and waits. The other redeems an introduction by dialing that identity. The relay bridges the held socket to the dialer, and the keyed session runs end to end between the two browsers.

Bounded resources

When one peer stops reading, the relay stops reading from the other. This backpressure caps the bytes in flight. An idle timeout reclaims silent sessions. A relayed connection costs buffers but no CapTP session state. The hosting app sets its own limits on live sessions and held registrations, as Rooms does. The relay counts bytes and sessions, never messages.

The same contract on every runtime

@glowcap/relay is the Deno reference implementation. Python, Rust, and Racket forward, apply backpressure, and reclaim idle sessions the same way.

Locators

A keyed-relay locator names the waiting peer’s key, and the dialing host reaches it through its configured relay URL (ADR-0034). noise-relay uses the same registration path and encrypts the CapTP stream between the peers. A browser can also ask the relay to dial a TCP or iroh locator, as described under Dialing a far peer. Choosing a transport lists them all, and the Noise guide covers the sealed path.

Dial

Choose noise-relay for an end-to-end sealed stream. Use keyed-relay only when the relay and network are already trusted. Each tab stops once the runtime and locator are ready, and the binding page covers connect, fetch, and call.

The snippets use wss:// and trust the operating system’s certificate store: Zig passes .system, and the bindings use the host WebSocket. The Zig provider also accepts cleartext ws on a network you already trust. Its tests use a local certificate authority, so none exercises a relay with a public certificate.

Noise

Zig

const std = @import("std");
const glowcap = @import("glowcap");
const relay_tls = @import("relay_tls");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // Noise_XK seals the session end to end; the relay forwards ciphertext.
    const relay_url = "wss://relay.example/relay";
    var tls = switch (relay_tls.initTlsOwner(io, allocator, .system)) {
        .ready => |ready| ready.owner,
        .failed => return error.RelayUnavailable,
    };
    defer switch (tls.release()) {
        .released => {},
        .busy, .failed => std.log.err("relay TLS teardown failed", .{}),
    };
    var entropy: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined;
    try io.randomSecure(&entropy);
    const transports: glowcap.driver.Transports = .{ .symbols = &.{.noise_relay}, .relay = .{
        .url = relay_url,
        .entropy_seed = entropy,
        .resolver_io = io,
        .tls_owner = tls,
    } };
    var hint_storage: [1]glowcap.ocapn.model.HintEntry = undefined;
    const peer_key = "<64 lowercase hex characters from the server>";
    const partner = glowcap.net.relay.noise.locator(peer_key, relay_url, &hint_storage);
    const session = try glowcap.driver.connect(
        allocator,
        io,
        transports,
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

TypeScript

import { Runtime } from "@glowcap/runtime";
import { noise, provider } from "@glowcap/relay";

// Noise_XK seals the session end to end; the relay forwards ciphertext.
const peerKey = "<64 lowercase hex characters from the server>";
const relayUrl = "wss://relay.example/relay";
const partner = noise.locator(peerKey, relayUrl);

await using runtime = await Runtime.open({
	providers: [provider({ relayUrl })],
});

Browser

import { connector, noise } from "@glowcap/relay";
import { init } from "@glowcap/web";

const relayUrl = "wss://relay.example/relay";
const web = await init({
	wasm: fetch("/glowcap_host.wasm"),
	connectors: [connector()],
});
await using runtime = web.runtime;
const partner = noise.locator("<64 lowercase hex characters>", relayUrl);

Python

from glowcap import Runtime, relay

# Noise_XK seals the CapTP stream end to end through the relay.
peer_key = "<64 lowercase hex characters from the server>"
relay_url = "wss://relay.example/relay"
partner = relay.noise.locator(peer_key, relay_url)

async with Runtime.open(providers=[relay.provider(relay_url)]) as runtime:

Rust

use glowcap::{relay, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// Noise_XK seals the CapTP stream end to end through the relay.
let peer_key = "<64 lowercase hex characters from the server>";
let relay_url = "wss://relay.example/relay";
let partner = relay::noise::locator(peer_key, relay_url);
let runtime = Runtime::open(RuntimeConfig::providers([relay::provider(
	relay::Config::dial_only(relay_url),
)]))
.await?;

Racket

(require glowcap/glowcap glowcap/glowcap-relay)

;; Noise_XK seals the CapTP stream end to end through the relay.
(define peer-key "<64 lowercase hex characters from the server>")
(define relay-url "wss://relay.example/relay")
(define partner (noise-relay-locator peer-key relay-url))
(define runtime
  (open-runtime #:providers (list (relay-provider #:relay-url relay-url))))

Keyed

Zig

const std = @import("std");
const glowcap = @import("glowcap");
const relay_tls = @import("relay_tls");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // The key names the peer; the hint names the relay that can reach it.
    const relay_url = "wss://relay.example/relay";
    var tls = switch (relay_tls.initTlsOwner(io, allocator, .system)) {
        .ready => |ready| ready.owner,
        .failed => return error.RelayUnavailable,
    };
    defer switch (tls.release()) {
        .released => {},
        .busy, .failed => std.log.err("relay TLS teardown failed", .{}),
    };
    var entropy: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined;
    try io.randomSecure(&entropy);
    const transports: glowcap.driver.Transports = .{ .symbols = &.{.keyed_relay}, .relay = .{
        .url = relay_url,
        .entropy_seed = entropy,
        .resolver_io = io,
        .tls_owner = tls,
    } };
    var hint_storage: [1]glowcap.ocapn.model.HintEntry = undefined;
    const peer_key = "<64 lowercase hex characters from the server>";
    const partner = glowcap.net.relay.keyed.locator(peer_key, relay_url, &hint_storage);
    const session = try glowcap.driver.connect(
        allocator,
        io,
        transports,
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

TypeScript

import { Runtime } from "@glowcap/runtime";
import { keyed, provider } from "@glowcap/relay";

// The key names the peer; the hint names the relay that can reach it.
const peerKey = "<64 lowercase hex characters from the server>";
const relayUrl = "wss://relay.example/relay";
const partner = keyed.locator(peerKey, relayUrl);

await using runtime = await Runtime.open({
	providers: [provider({ relayUrl })],
});

Browser

import { connector, keyed } from "@glowcap/relay";
import { init } from "@glowcap/web";

const relayUrl = "wss://relay.example/relay";
const web = await init({
	wasm: fetch("/glowcap_host.wasm"),
	connectors: [connector()],
});
await using runtime = web.runtime;
const partner = keyed.locator("<64 lowercase hex characters>", relayUrl);

Python

from glowcap import Runtime, relay

# The key names the peer; the hint names the relay that can reach it.
peer_key = "<64 lowercase hex characters from the server>"
relay_url = "wss://relay.example/relay"
partner = relay.keyed.locator(peer_key, relay_url)

async with Runtime.open(providers=[relay.provider(relay_url)]) as runtime:

Rust

use glowcap::{relay, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// The key names the peer; the hint names the relay that can reach it.
let peer_key = "<64 lowercase hex characters from the server>";
let relay_url = "wss://relay.example/relay";
let partner = relay::keyed::locator(peer_key, relay_url);
let runtime = Runtime::open(RuntimeConfig::providers([relay::provider(
	relay::Config::dial_only(relay_url),
)]))
.await?;

Racket

(require glowcap/glowcap glowcap/glowcap-relay)

;; The key names the peer; the hint names the relay that can reach it.
(define peer-key "<64 lowercase hex characters from the server>")
(define relay-url "wss://relay.example/relay")
(define partner (keyed-relay-locator peer-key relay-url))
(define runtime
  (open-runtime #:providers (list (relay-provider #:relay-url relay-url))))

Listen

A listening peer registers its durable key with the relay and keeps the registration alive while it accepts sessions. Persist the identity seed so the advertised locator survives a restart. TypeScript, Python, Rust, and Racket provide managed noise-relay listeners. Zig registers through driver.listen with the "glowcap_relay_tls" module, which builds Mbed TLS from source. It uses the operating system’s certificate store for wss://. A browser page registers through @glowcap/web instead.

For cleartext keyed registration, use resident(.keyed) in Zig, keyed.listen in TypeScript, Python, and Rust, or listen-keyed-relay in Racket. The locator is still identity-addressed, and the relay path is not sealed.

Zig

const std = @import("std");
const glowcap = @import("glowcap");
const relay_tls = @import("relay_tls");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // Register this key at the relay; Noise_XK seals every accepted CapTP stream.
    const seed = @as([32]u8, @splat(7)); // load durable secret bytes in a real service
    const secret = glowcap.foundation.crypto.SecretKey.fromSeed(seed);
    var tls = switch (relay_tls.initTlsOwner(io, allocator, .system)) {
        .ready => |ready| ready.owner,
        .failed => return error.RelayUnavailable,
    };
    defer switch (tls.release()) {
        .released => {},
        .busy, .failed => std.log.err("relay TLS teardown failed", .{}),
    };
    var entropy: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined;
    try io.randomSecure(&entropy);
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .symbols = &.{.noise_relay}, .relay = .{
            .url = "wss://relay.example/relay",
            .entropy_seed = entropy,
            .resolver_io = io,
            .tls_owner = tls,
            .registration = .{ .url = "wss://relay.example/register" },
        } },
        glowcap.ocapn.model.transport.noise_relay,
        .{ .designator = "" },
        .{ .keyed = secret },
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    const uri = try glowcap.ocapn.model.uri.writePeer(allocator, (try server.advertisedLocator()));
    defer allocator.free(uri);
    std.debug.print("{s}\n", .{uri}); // Noise seals the relay path end to end

    try serve(server);
}

TypeScript

import type { Argument } from "@glowcap/runtime";
import { noise } from "@glowcap/relay";

// Register this key at the relay; Noise_XK seals every accepted CapTP stream.
const seed = crypto.getRandomValues(new Uint8Array(32));
await using server = await noise.listen({
	relayUrl: "wss://relay.example/relay",
	registerUrl: "wss://relay.example/register",
	seed,
});

Python

import os
from glowcap import Argument, relay

# Register this key at the relay; Noise_XK seals every accepted CapTP stream.
seed = os.urandom(32)  # load durable secret bytes in a real service
async with await relay.noise.listen(
    "wss://relay.example/relay",
    "wss://relay.example/register",
    seed=seed,
) as server:

Rust

use glowcap::{relay, Argument};

// Register this key at the relay; Noise_XK seals every accepted CapTP stream.
let seed = [7u8; 32]; // replace with durable secret bytes across restarts
let server = relay::noise::listen(
    "wss://relay.example/relay",
    "wss://relay.example/register",
    relay::ListenOptions {
        identity: relay::ListenerIdentity::Seed(seed),
        ..relay::ListenOptions::default()
    },
)
.await?;

Racket

(require glowcap/glowcap
         glowcap/glowcap-relay)

;; Register this key at the relay; Noise_XK seals every accepted CapTP stream.
(define seed (make-bytes 32 7)) ; Replace with durable secret bytes.
(define server (listen-noise-relay
                "wss://relay.example/relay"
                "wss://relay.example/register"
                #:seed seed))
(printf "~a\n" (server-uri server)) ; hand this locator to partners
(define host (server-host server))
(define (accept-session) (accept server))

Running one

The reference relay runs from a repository checkout with Deno installed. For iroh, point GLOWCAP_LIB_DIR at a matching released C SDK’s lib/ directory, as the runtime installation guide describes. Using that SDK needs no Zig or Rust compiler. Contributors can instead run zig build and zig build iroh-abi in their working checkout.

Run from the repository root:

deno run --allow-all bindings/ts/relay/serve.ts 9000
# DENO-RELAY-READY 9000

It listens on localhost. Dial /relay?to=host:port for TCP or /relay?locator=URI for iroh, with the URI percent-encoded. Iroh requires the server’s full advertised locator, including direct addresses reachable from the relay. This reference relay does not use iroh discovery.

The relay allows any target and reclaims silent sessions after the idle timeout that GLOWCAP_RELAY_IDLE_MS sets. Allowed targets and connection limits belong to the app that hosts the relay, as in the Rooms limits.rs. The relay README covers the package. The browser peer lives in the TypeScript binding.