Core Concepts

Tubo is built around a small set of orthogonal concepts: roles, overlays, clusters, namespaces, service identities, and a capability-based trust model. Understanding these makes every command and configuration option obvious.

Roles

Every tubo process runs in one of four roles:

Role	Command	What it does
relay	`tubo relay`	Public bootstrap node. Assists NAT traversal via libp2p circuit relay v2. Does not see traffic content.
attach	`tubo attach`	Publishes a local HTTP service into the swarm. Signs announcements, accepts libp2p streams, forwards to origin.
connect	`tubo connect`	Opens a local HTTP listener. Discovers the service, dials it, and proxies traffic through a libp2p stream.
gateway	`tubo gateway`	HTTP ingress gateway that routes requests to swarm services by `Host` header. Acts as a shared connect proxy.

Overlays, clusters and namespaces

Tubo organises its address space into a three-level hierarchy:

Overlay — a libp2p swarm defined by a shared swarm key (PSK) and a set of bootstrap/relay peers. The public Tubo network is the tubo-public overlay.
Cluster — a trust domain within an overlay. A cluster has an authority keypair; only signed announcements from authority-approved peers are accepted inside it.
Namespace — a sub-scope within a cluster. Discovery, service identities, and access policies are all namespace-scoped.

When you run tubo join you join the public overlay and are placed in the home/default cluster/namespace. You can create your own clusters with tubo create cluster/<name>.

Service identity

Every service has two names:

display name — a human-readable label (e.g. lmstudio). Display names are not unique.
service ID — a stable cryptographic identity derived from the service owner key (e.g. svc_abc123def456). Authorisation always binds to the service ID.

When you run tubo attach http://127.0.0.1:1234 --name lmstudio, Tubo generates or reuses a stable service owner key under ~/.config/tubo/clusters/.../services/ and derives the service ID from it. The service ID remains stable across restarts.

Discovery

In collaborative namespaces, service announcements are published over libp2p GossipSub on an opaque Discovery V3 topic derived from the namespace discovery entry, not from public cluster and namespace IDs alone. Each announcement is Ed25519-signed by the service owner key and carries a PublishLease/ServiceClaim chain signed by the cluster authority.

Clients validate the full chain before routing to a peer:

Topic is correct for the current cluster/namespace discovery entry.
Announcement signature is valid (service owner key).
ServiceClaim is signed by a trusted authority.
Nonce has not been seen before (replay protection).

In the public home/default namespace, ambient discovery is disabled. Services are unlisted — only reachable via a signed invite token. Use a private cluster for ambient discovery.

Access control

Tubo uses a capability-based access model with three main concepts:

PublishLease — authorises a service peer to publish in a namespace. Signed by the cluster authority.
ConnectAccessLease — short-lived token authorising a client to open streams to a specific service. Renewed via a ConnectRefreshLease.
ShareInvite — signed one-time invitation token. Carrying it redeems a ConnectAccessLease from the service's grant endpoint. One-time: a second redemption is denied.

NAT traversal

Tubo uses libp2p's built-in NAT traversal stack:

Direct dial — attempted first with a short timeout (default 750ms).
Circuit relay v2 — automatic fallback when direct dial fails. Traffic relayed end-to-end encrypted through a relay node.
Hole punching — libp2p coordination protocol that upgrades relayed connections to direct ones when NAT allows it.

No inbound ports are required on service hosts. Only the relay needs a public TCP port.

Configuration precedence

CLI flag  >  env var  >  config file  >  default  >  interactive prompt

Configuration lives at ~/.config/tubo/config.yaml by default. Override with --config-dir or XDG_CONFIG_HOME.

Next steps

Private Swarms — build an isolated network with a PSK
Access Control — grants, leases, revocation
Security Model — full trust model and non-goals