CLI Reference
Complete reference for every tubo subcommand, flag, and environment variable.
CI=true or --non-interactive is set.
tubo join
Configure this machine for an existing swarm.
# Join the public Tubo network (default) $ tubo join # Join a private swarm manually $ tubo join overlay/manual \ --relay /ip4/1.2.3.4/tcp/4001/p2p/12D3... \ --swarm-key ./swarm.key # Join an existing cluster with an invite token $ tubo join cluster/myteam --token <cluster-invite>
tubo relay
Start a relay / bootstrap node (typically on a machine with a public IP).
$ tubo relay \ --swarm-key ./swarm.key \ --public-addr /ip4/1.2.3.4/tcp/4001 \ -d
Key flags:
--swarm-key <path>— path to PSK swarm key file--public-addr <multiaddr>— publicly reachable address announced to peers--listen <multiaddr>— libp2p listen address (default/ip4/0.0.0.0/tcp/4001)--health-listen <addr>— HTTP health endpoint (default127.0.0.1:8092)-d / --detach— detach and run in background
Firewall requirements: TCP 4001 inbound (libp2p), TCP 8092 optional (health check).
tubo attach
Publish a local HTTP service or raw TCP/TLS endpoint into the swarm.
# HTTP service $ tubo attach http://127.0.0.1:1234 --name lmstudio -d # Raw TCP / TLS passthrough $ tubo attach tcp://127.0.0.1:8443 --name tlsdemo -d
Key flags:
--target <url>— origin target URL, for examplehttp://...ortcp://...--port <n>— legacy shorthand forhttp://127.0.0.1:<n>--name <name>— display name for the service--cluster / --namespace— override current cluster/namespace-d / --detach— detach and run in background
tubo connect
Open a local HTTP or TCP listener that tunnels to a remote service.
# By name (discovery-enabled namespaces only) $ tubo connect myapi --local 127.0.0.1:9000 # By invite token (works everywhere, including public/invite-only) $ tubo connect --token eyJ... --local 127.0.0.1:9000 # TCP service invite $ tubo connect --token eyJ... --local 127.0.0.1:9443 # Detached mode $ tubo connect --token eyJ... --local 127.0.0.1:9000 -d
Key flags:
--local <addr>— local listen address (auto-assigned if omitted)--token <invite>— share invite token for invite-only services--cluster / --namespace— override current cluster/namespace-d / --detach— detach and run in background--json— machine-readable output
tubo gateway
Run an HTTP gateway that routes requests to swarm services by Host header.
$ tubo gateway --listen :8443 -d # Access a service via the gateway $ curl -H 'Host: lmstudio' http://localhost:8443/v1/models
tubo get / describe / inspect
# Services in the swarm $ tubo get services $ tubo get services -n mynamespace $ tubo get services -A # all namespaces $ tubo describe service/lmstudio $ tubo inspect service/lmstudio --json $ tubo watch services --timeout 30s # Local resources $ tubo get overlays $ tubo get clusters $ tubo get namespaces $ tubo get secrets $ tubo describe cluster/myteam $ tubo describe namespace/default $ tubo describe secret/namespace-discovery/myteam/default
describe process/... and inspect process/... --json expose detached process runtime state, including network reachability state/reason, recovery timestamps, and next-refresh retry timing for bridge/connect children. describe pipe/... and inspect pipe/... --json expose the saved pipe definition for detached connect. Event timestamps use ... ago labels, while lease expiry fields keep their existing expires in labels. For attached services, describe also shows whether the service-scoped grant endpoint is enabled, plus the effective connect policy and grant protocol when available. In foreground attach, the running-in-foreground notice now waits until publish authorization is resolved, so missing grant-peer errors appear before any success-style hint.
tubo create / use / share
# Create local resources $ tubo create cluster/myteam $ tubo create namespace/production $ tubo create service/myapi # Switch active context $ tubo use cluster/myteam $ tubo use namespace/production # Share access $ tubo share cluster/myteam --namespace default --role member $ tubo share service/myapi --expires 24h $ tubo rotate secret/namespace-discovery/myteam/default --grace 24h
tubo ps / logs / start / restart / stop / rm
$ tubo ps # list local detached processes $ tubo logs process/attach-myapi # follow logs $ tubo start pipe/connect-myapi-1234 # start from saved pipe definition $ tubo restart pipe/connect-myapi-1234 # restart from saved pipe definition $ tubo stop process/attach-myapi # stop a process $ tubo stop pipe/connect-myapi-1234 # stop the runtime only $ tubo rm pipe/connect-myapi-1234 --force # remove saved pipe definition $ tubo rm --stale # remove terminated process state
tubo grants
# Authority side $ tubo grants serve --cluster myteam --namespace default $ tubo grants pending $ tubo grants approve gr_123 --ttl 168h $ tubo grants deny gr_123 # Requester side $ tubo grants request service/myapi --peer /ip4/1.2.3.4/tcp/4001/p2p/12D3... $ tubo grants request service/myapi --poll $ tubo grants history
tubo keygen / id / config / doctor
$ tubo keygen swarm --out swarm.key # generate a PSK swarm key $ tubo id from-seed my-service-seed # derive PeerID from a seed $ tubo config validate # validate current config $ tubo config print # print config (secrets masked) $ tubo doctor # run connectivity health checks $ tubo version # show version and protocol info
Environment variables
| Variable | Description |
|---|---|
LIBP2P_PRIVATE_NETWORK_KEY | Path to swarm.key file |
LIBP2P_PRIVATE_NETWORK_KEY_B64 | Base64-encoded 32-byte PSK (alternative to file) |
LIBP2P_ALLOWED_PEERS | Comma-separated PeerID allowlist |
TUBO_DEFAULT_PUBLIC_BUNDLE_URL | Override the default public bundle URL |
CI | Set to true to disable interactive prompts and implicit join |
XDG_CONFIG_HOME / XDG_DATA_HOME | Override default config / data directories |
Process state directories
~/.config/tubo/ — configuration, swarm key, cluster state ~/.local/share/tubo/processes/ — detached process metadata ~/.local/share/tubo/logs/ — process log files ~/.local/share/tubo/run/ — PID files and sockets