Cubes

A cube is a machine your yeti run on. This computer is your first cube. You can add other machines you own (a spare laptop, a mini in the closet, a server) or launch one in your own AWS account. Together your cubes form a cluster that keeps your yeti, settings and sealed secrets in sync.

This computer's cube

yeti installs this computer's cube on first launch as a background service named dev.yeti.cube: a launchd agent on macOS, a systemd user unit on Linux, a Windows service on Windows. It starts on its own and restarts if it stops, so your yeti keep working with the app closed.

It listens on this computer only (127.0.0.1), and the app talks to it over mutual TLS 1.3, even on the same machine.

The Cubes page

• The tray shows every cube. Select one to see where it runs, whether it's online, and whether it leads.
• Connection and Trust show the link to your cube, your cluster's CA fingerprint, certificate expiry, and whether your cluster can survive losing a cube.
• Logs reads any cube's log live, with Everything or Warnings and Follow.
• Trusted devices, Cloud accounts and Launch in the cloud are covered below and in Cloud cubes.

How a cluster stays up

Cubes replicate their state with raft. Any majority of voting cubes can keep going, and if the leader goes away the rest elect a new one.

Voting cubes	Can lose
1 or 2	none
3	1
5	2

So with just this computer and one other cube, the cluster stops when either is off. To keep your yeti working while this computer sleeps, the cubes that stay on must be a majority: for example, this computer plus two always-on cubes.

A new cube joins as a non-voter and promotes itself once it has caught up, so a cube that never starts can't cost you your quorum.

Work moves on its own. The leader hands each task to the least busy live cube on a short lease. If a cube dies, its leases lapse and its tasks move to another cube, up to three attempts.

Add a machine you own

The other machine needs the standalone cube program: a single binary with no GUI, built from cmd/cube in the yeti source (go build ./cmd/cube). On this computer, the yeti app includes the same commands as yeti cube ….

1. In yeti, open Cubes and choose Add a machine. yeti makes a join code that works once and expires after 10 minutes, and shows the command to run. (cube token create makes one in a terminal: an hour by default, up to 24 hours with --ttl.)

2. On the other machine, run it:

   cube join <address> --token <token> --listen 0.0.0.0 --advertise <its-ip> --install
   

<address> must be a cube the new machine can reach. This computer's cube listens only on this computer, so unless you've changed its reach (below), use the reverse join instead.

When the new machine can't reach you

Laptops usually sit behind NAT, so let this computer dial the new machine:

1. On the new machine, run the join with --wait-for-cluster. It waits with a one-time bootstrap certificate and prints that certificate's SHA-256 fingerprint.

   cube join --wait-for-cluster --token <token> --listen 0.0.0.0 --advertise <its-ip> --install
   

2. On this computer, before the join code expires:

   yeti cube peers connect <its-ip>:7443 --fingerprint <fingerprint>
   

Each side checks the other first: this computer accepts only the exact certificate you pinned, and the new cube accepts only a cube from the cluster named in its token. Then the new cube joins, and this computer keeps a connection open to it. Carry the fingerprint over a channel you trust: anyone who can swap it can swap the machine.

Who can connect: reach

cube reach sets who can open a connection to a cube. Changes apply after cube restart.

Reach	Listens on	Use it for
local	127.0.0.1 only	Laptops. Other cubes can't dial it; it dials them, and they reach it back over those connections
network	all interfaces	Machines on your network, at its LAN address
anywhere	all interfaces	A public IP or DNS name (--advertise). Open ports 7443 and 7444

Whatever you pick, every connection is mutual TLS 1.3 with certificates your cluster issues. Being reachable lets a machine knock; it doesn't let it in.

Trusted devices

Devices talk to your cluster without running a cube. Each gets its own certificate.

• Add one makes a single-use code for a device with full control. On the device, run cube remote add home <address> --token <token>.
• For a device that may run tasks but not change the cluster, use cube token create --client. It shows as tasks only.
• Revoke cuts a device off. Every cube turns it away at once, even mid-connection.

Remove a cube

cube members remove <name> removes a cube and revokes its certificate. For a cloud cube, use Remove on its card instead, which also deletes what yeti made in AWS.

Command reference

Command	What it does
cube init, cube join	Start a cluster, or join one
cube install, uninstall, start, stop, restart, status	The service (uninstall keeps the cube's data)
cube reach, cube peers	Who can connect, and the connections this cube keeps
cube members, cube token, cube clients, cube remote	Cubes, join codes, devices, and using a cluster without a cube
cube config, cube cert	This cube's settings and certificates
cube task	Tasks (try cube task submit sleep 30s)

Where a cube keeps its state

cube config path prints it. By default:

System	Directory
macOS	~/Library/Application Support/yeti/cube
Linux	~/.local/share/yeti/cube
Windows	%LOCALAPPDATA%\yeti\cube
As root	/Library/Application Support/yeti/cube (macOS), /var/lib/yeti/cube (Linux)

Inside: config.yaml, keys and certificates in tls/, raft state in raft/, service logs in logs/, and peers.json. Treat it as private; Security explains why.

Good to know

• On Linux, user services stop at logout unless lingering is on: loginctl enable-linger.
• Leases use each machine's clock, so keep clocks roughly in sync (NTP).
• A cube that just restarted answers nothing until it has caught up.