Cluster & Mesh

A Kaba cluster is the set of devices you own, joined into one encrypted private network. There is no account with a third party and no port to open. Once two devices are in the same cluster you can open a terminal on the other one, browse its files, run inference or training on it, or send your traffic out through it.

This page describes a personal cluster: you create the tickets, you join the devices, you evict them. Under Kaba Enterprise, devices are enrolled into a fleet, grouped, and managed centrally, and the organisation can revoke a device’s keys and data remotely. The mesh underneath is the same. See what fleet control changes.

Each device runs kabactl. Peers connect directly where the network allows it and fall back to a relay when it does not. Every connection is end-to-end encrypted between node keys. See protocols for what travels over the mesh.

Add a device

1. Create a ticket on a device already in the cluster.

kabactl cluster invite --name laptop --ttl 15

Join ticket (valid for 15 minutes):

  kaba_invite_…

On the new node:
  kabactl cluster join kaba_invite_…

--name is a label for the token and --ttl is its lifetime in minutes (default 15). A ticket can be used once.

In the client: Settings → Devices → Invite a device. Tickets made there are valid for 5 minutes.

2. Join from the new device.

kabactl cluster join kaba_invite_…

or paste the ticket into Settings → Devices → Join a cluster. The device joins under its hostname.

3. Start the server on the new device if it is not already running (kabactl server, or the service). Within about a minute both devices show each other as online with their capabilities.

[todo: add screenshot of Settings → Devices and of parts Invite a device, the join ticket, Join a cluster, the device table (Status, Name, Role, Node ID, Last Seen).]

Clocks must agree

Peers reject requests whose timestamp is more than 60 seconds off. If joins or pings fail between two machines that can otherwise reach each other, check that both have the correct time.

Manage peers

kabactl cluster list                 # all known peers
kabactl cluster show gpu-tower       # details for one
kabactl cluster ping gpu-tower       # round trip and latency
kabactl cluster evict old-laptop -y  # remove a device

Peers can be named by their cluster name or their node ID.

Evicting a device removes it from every peer and leaves a tombstone so it cannot quietly rejoin with the same identity.

kabactl cluster tombstones           # list evicted node IDs
kabactl cluster rejoin <NODE_ID>     # clear a tombstone

If a peer shows as known but cannot be reached because its keys are missing, kabactl cluster repair re-establishes them.

What you can do across the cluster

Capability	How to use it	Peer setting that allows it
Terminal on a peer	Terminal → Open a terminal on… (Ctrl+Shift+P), or a device’s menu in Settings → Devices
Browse a peer’s files	Files → Device switcher
Synced folder	Files → Kaba Sync
Inference on a peer	Policy → Inference target, or kabactl ask --peer	accept_remote_inference
Training on a peer	Train dialog in the client, or kabactl train --node	accept_remote_training
Containers on a peer	Settings → Containers → Manage on	enable_peer_exec
Exit node	Settings → Devices → device menu → Use as exit
Publish a service	Hippocampus → Services → Expose

All three peer settings default to on. Turn them off in the peer’s config.toml.

Exit nodes

Choosing a peer as your exit tunnels all local proxy traffic through it, so sites see that peer’s network. Use it to reach your home connection from a café, or an office server from the road. Switching exits does not affect connections that are already open. Revert to direct routing turns it off.

Network settings

These live under cluster_options.

Goal	Setting
Keep a node off the mesh	cluster_enabled = false
Use your own relay	relays = ["https://relay.example.com"]
Never connect directly	relay_only = true
Also use iroh’s public relays or discovery	include_default_relays = true, n0_discovery = true

By default a node uses only https://relay.kaba.dev and does not use any public discovery service.

Headless nodes

A node with no desktop session, such as a server or a container, is headless. It joins and serves like any other peer but has no client attached. kabactl detects this from whether a real user account exists; set headless = true or false in config.toml to force it. See deployment.