Files
skills/public/hanzo-relay.md

6.1 KiB

Hanzo Relay - Cloud Tunnel for Hanzo Apps

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-bot.md, hanzo/hanzo-code.md, hanzo/hanzo-extension.md

Overview

Hanzo Relay (crate name: hanzo-relay, internally hanzo-tunnel) is a Rust library that connects any local Hanzo app (dev, node, desktop, bot, extension) to the cloud relay at api.hanzo.ai for remote management and multiplayer. WebSocket-based with automatic reconnection, JSON wire protocol, auth via JWT or API key, and optional mDNS LAN discovery. Think ngrok built into every Hanzo app.

Why Hanzo Relay?

  • One crate, all apps: Same tunnel for dev agents, nodes, desktop apps, bots, browser extensions
  • Register + stream: Apps register with the cloud and stream events (chat deltas, exec output)
  • Remote commands: Cloud sends commands (chat messages, config changes, approvals) back to instances
  • Service exposure: Expose local HTTP/WS/TCP ports through the tunnel (like ngrok)
  • Auto-reconnect: Exponential backoff with configurable limits
  • LAN discovery: Optional mDNS for local network peer discovery (feature-gated)
  • Auth: JWT from hanzo.id or API keys (sk-hanzo-...)

Tech Stack

  • Language: Rust (edition 2021)
  • Crate: hanzo-relay v0.1.0
  • Transport: tokio-tungstenite (WebSocket with native-tls)
  • Async: Tokio (rt, macros, sync, time, net)
  • Serialization: serde + serde_json
  • Error handling: thiserror
  • Logging: tracing
  • Optional: mdns-sd (LAN discovery), rustls (TLS alternative)

Repo: github.com/hanzoai/relay

When to use

  • Connecting a Hanzo dev agent to cloud management (app.hanzo.bot)
  • Building apps that need remote control from the Hanzo dashboard
  • Exposing local development servers through cloud tunnel
  • Peer discovery between Hanzo apps on a LAN

Quick reference

Item Value
Crate hanzo-relay
Repo github.com/hanzoai/relay
Version 0.1.0
License MIT
Default relay wss://api.hanzo.ai/v1/relay
Default features reconnect

Usage

Connect to Cloud

use hanzo_tunnel::{connect, TunnelConfig, AppKind};

let conn = connect(TunnelConfig {
 relay_url: "wss://api.hanzo.ai/v1/relay".into(),
 auth_token: "sk-hanzo-...".into(),
 app_kind: AppKind::Dev,
 display_name: "z-macbook".into(),
 capabilities: vec!["chat".into(), "exec".into()],
 ..Default::default()
}).await?;

// Send events to cloud
conn.send_event("chat.delta", serde_json::json!({"text": "hello"})).await?;

// Receive commands from cloud
while let Some(cmd) = conn.recv_command().await {
 println!("got: {} {}", cmd.method, cmd.params);
 conn.respond(cmd.id, true, None).await?;
}

Connect and Wait for Registration

use hanzo_tunnel::connect_and_register;

let conn = connect_and_register(config).await?;
println!("Session URL: {:?}", conn.session_url);
// e.g., https://app.hanzo.bot/i/abc-123

Expose Local Services

use hanzo_tunnel::expose::{expose, ExposedService, ExposeProtocol};

expose(&conn.event_sender(), ExposedService {
 name: "app-server".into(),
 local_addr: "127.0.0.1:3000".into(),
 protocol: ExposeProtocol::Http,
 subdomain: Some("my-dev".into()),
}).await?;

Wire Protocol

All frames are JSON over WebSocket text messages, tagged by type:

Direction Frame Purpose
Instance -> Cloud register Register app with capabilities and metadata
Cloud -> Instance registered Acknowledge with session_url
Instance -> Cloud event Stream data (chat.delta, exec.output, etc.)
Cloud -> Instance command Send command (chat.send, config.update, etc.)
Instance -> Cloud response Reply to a command (ok/error + data)
Bidirectional ping / pong Keep-alive heartbeat

App Kinds

pub enum AppKind {
 Dev, // Development agent
 Node, // Blockchain/AI node
 Desktop, // Desktop application
 Bot, // Bot instance
 Extension, // Browser/IDE extension
}

Feature Flags

Feature Default Description
reconnect Yes Auto-reconnect with exponential backoff
mdns No LAN discovery via mDNS (_hanzo._tcp.local.)
tls-rustls No Use rustls instead of native-tls

Key Files

File Purpose
src/lib.rs TunnelConfig, TunnelConnection, connect(), connect_and_register()
src/protocol.rs Frame enum, all payload types, AppKind
src/transport.rs WebSocket transport with reconnection loop
src/auth.rs AuthToken (JWT vs API key auto-detection)
src/expose.rs Service exposure (HTTP/WS/TCP tunneling)
src/registry.rs Instance type, InvokeParams, InvokeResult
src/discovery.rs mDNS advertisement and discovery

Auth

pub enum AuthToken {
 Jwt { token: String }, // JWT from hanzo.id
 ApiKey { key: String }, // sk-hanzo-... API key
}

// Auto-detects: 2+ dots = JWT, otherwise API key
let token = AuthToken::from_string("sk-hanzo-abc123");

Transport Config

pub struct TransportConfig {
 pub url: String, // wss://api.hanzo.ai/v1/relay
 pub auth: AuthToken,
 pub initial_backoff: Duration, // 1s
 pub max_backoff: Duration, // 60s
 pub heartbeat_interval: Duration, // 30s
 pub connect_timeout: Duration, // 10s
}

TunnelConnection API

conn.send_event(event, data).await?; // Stream event to cloud
conn.recv_command().await; // Next command (None = closed)
conn.respond(id, ok, data).await?; // Reply to command
conn.respond_error(id, msg).await?; // Reply with error
conn.event_sender(); // Clone sender for spawned tasks
conn.shutdown(); // Graceful disconnect
conn.is_connected(); // Check liveness
  • hanzo/hanzo-bot.md - Bot framework (uses relay for cloud management)
  • hanzo/hanzo-code.md - Dev agent (registers via relay)
  • hanzo/hanzo-extension.md - Browser/IDE extensions (tunnel back to cloud)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: tunnel, websocket, remote-management, cloud, rust, ngrok Prerequisites: Rust toolchain, Tokio runtime