Skip to content
TowonelTowonel

Architecture

Two processes, one persistent QUIC tunnel.

Hub + edge

Section titled “Hub + edge”

One binary. Can run combined on a single VPS (TOWONEL_HUB_ENABLED=true, TOWONEL_EDGE_ENABLED=true) or split into separate processes for HA.

  • Edge accepts TLS on :443, peeks the SNI, forwards over an open QUIC stream to the matching agent. iroh QUIC binds UDP :51820.
  • Hub serves the control plane on :8443 and the hub↔edge link on :51444. State lives in SQLite (default) or Postgres (multi-replica).

The hub cannot decrypt tenant traffic in passthrough mode.

Agent

Section titled “Agent”

Runs wherever your origin is reachable. Dials the edge over QUIC. Stateless: one invite token, no disk, no init. Replicas share the identity derived from the invite seed.

Reachability

Section titled “Reachability”

The edge reverse-dials the agent for user traffic, so the agent’s iroh endpoint must be reachable. Either advertise a routable host:port (Kubernetes NodePort UDP, or TOWONEL_AGENT_EXTRA_LOCAL_ADDRS), or configure a fallback relay.

Identity

Section titled “Identity”
  • Tenant: ML-DSA-65 (FIPS 204). Each tenant signs their own config entries; the hub operator cannot forge entries.
  • Transport: Ed25519 via iroh.
  • Agent auth: invite token (tt_inv_2_…) carries the tenant identity. The hub signs short-lived EdgeCreds the agent presents on connect.
  • Client auth: standard TLS handshake.