Machines that are not in the same room

Running work on machines elsewhere, over a private overlay network between them: what joining gives a machine, what it does not give, and what the fleet can see about each one.

A fleet does not have to be one rack, one office or one country. A machine in a colocation cage, a build box under somebody's desk and a laptop on a hotel network can all be part of the same fleet, and the way they are joined is a private overlay network: a peer-to-peer encrypted network your machines opt into, where each machine has a stable name and address that exist only inside that network.

Work still travels the way it travels anywhere else — the control plane opens an SSH connection outward to the machine it wants to use. The overlay changes one thing only: it makes that connection possible without publishing anything to the public internet. No port is forwarded, no firewall hole is opened, and nothing the product runs on a runner listens beyond loopback.

Joining the network is not being trusted

Everything else here depends on this one, and it is the one most often read backwards.

A machine that joins the overlay is reachable. That is all it is. Reachable means a route exists between the control plane and that machine. It does not mean the machine is known to the fleet, that it holds the product's binaries, that it has a seat, or that it may be given one line of work.

Admission is a separate, deliberate act, and it is the one that grants something. The machine generates its own key material locally; you admit it from the control plane, which signs a record naming that machine and binding the name to the key. Until that record exists the machine is a stranger: the fleet shows it as present on the network and not admitted, and nothing dispatches to it.

⛔ A machine that joins the overlay has been given a route, not a permission. Reading membership as trust is the one mistake here that would cost you something, because it is the assumption under which an unknown machine on your network starts to look like part of your fleet.

The fleet counts the two populations separately for exactly this reason — how many machines are on the network, and how many of those are admitted. The gap between the two numbers is the thing worth looking at, and it is a number rather than a feeling. See the fleet screen for where those counts are shown, and machines, enrollment and authentication for what admission checks and what it writes.

⚠ Direction matters, and it is not symmetrical. The control plane connects outward to machines. Machines never dial the control plane, never poll it, and hold no credential to it. So the overlay is a path the control plane can use; it is not a way for a machine to reach in.

What leaves your fleet for the network

Short enough to audit, which is the point of writing it down. Three things cross the boundary when you run an overlay, and the last column is the one to read — who says so, because a property we can observe and a property the provider states are not the same kind of claim.

what crosses	what it is	who says so
coordination traffic	Each machine talks to the provider's coordination service to learn which machines exist, their public keys and how to reach them. It is what makes the network a network.	The provider's own statement. We do not inspect their coordination service, and this page does not claim to.
relayed traffic, when there is no direct path	When two machines cannot open a direct path — a restrictive NAT, a hostile firewall — traffic falls back to a relay the provider runs. The provider states that a relay forwards an encrypted stream it cannot read.	The provider's statement for the encryption; measured here for the path. The fleet reads back, per machine, whether its path is direct or relayed, so you can see which machines are in this case.
telemetry to the provider	Turned off by you when you install the client, before the first packet.	Measured here, as a posture. The fleet reads the telemetry setting back per machine and shows it. What we can say is that the setting is off; whether every code path in a third-party client honours its own setting is that client's business and not something this product inspects.

⚠ This list is the cost of the overlay, and it is not the whole egress question. What a run is allowed to reach is a different boundary with its own rules, its own policy document and its own refusals — see what the egress door protects you from. A machine being on your overlay changes nothing about what an agent on it may dial.

What the fleet reads back, per machine

Per machine: whether it is on the network, its name and address there, whether its path is direct or relayed, whether it is admitted, since when it has been trusted, its telemetry posture, and its seats. From a terminal, saphan mesh probe <machine> measures one admitted machine on its own host and records the answer, and saphan mesh status lists every admitted machine with its reading and the overlay nodes that belong to no admitted machine (saphan mesh).

And when there is nothing to report, the fleet says which absence it is. This is the part that is easy to skim past and is genuinely the feature:

what you see	what it means	what to do
not measured yet	Nobody has asked this machine. The fleet is not claiming the machine is healthy or broken — it is claiming it has no reading.	Take a reading. An absence here is about the fleet, not about the machine.
no client installed	The machine was asked, and the overlay client is not on it.	Install the client. This is the ordinary state of a machine you have just added to the record and not yet joined.
installed, not a node	The client is on the machine and the machine has not joined the network — most often a credential that was never applied, or one that expired before it was used.	Join it with a current credential.
could not be reached	The fleet asked and got nothing back.	Diagnose the path, not the machine's configuration. This is the only one of the four that is a live problem rather than a step not yet taken.

⛔ A blank cell is not one of the options. All four of these would render as an empty space in a table that did not distinguish them, and they have four different answers — one of which is "do nothing, this is normal". Collapsing them into "unknown" moves the work of telling them apart from the product to you, at the moment you are least able to do it.

Adding a machine

Four steps. Read step 1 before you plan around this, because it is the one that is not ours.

Generate the joining credential — in the provider's console, by your own hand. You sign in to the overlay provider, mint a credential for the machine you are about to add, and copy it. ⚠ Doing this from the product is DESIGNED and is not built. There is no screen and no command in this product that mints one. What exists is the manual act; what is exercised is the manual act; what is therefore not proven is any flow that assumes a machine can be enrolled onto the network without you visiting the provider's console — including unattended provisioning of a new machine end to end.
Install the overlay client on the machine and join with that credential, with the client's telemetry disabled. The machine now has a name and an address on the network.
Look at the fleet. The machine appears as present on the network and not admitted — a stranger. Nothing will be dispatched to it in this state, and that is the correct state for a machine whose only qualification so far is that it can be reached.
Admit it: install the product's binaries, admit the machine from the control plane so its identity is signed into the record, and give it its class and its seats. Only now is it a machine the fleet will give work to.

Steps 2 to 4 are the ordinary install, and they are the same steps for a machine on the overlay as for a machine on your own LAN — see the whole install and verifying an install. The overlay is a transport decision, not a different product.

Coordination you host yourself, and air-gapped fleets

The overlay provider this product supports can be run with a coordination service you host yourself, so the traffic in the first row of the table above never leaves your own network. That is the shape an air-gapped or strictly-contained deployment needs.

⚠ State: DESIGNED. It is a deployment the provider supports and that this product has not exercised. What is therefore not proven: that the product's machine records, transport configuration and readbacks behave identically against a self-hosted coordination service; and whether anything in the four absence states above depends on the provider's own service being reachable. Do not plan an air-gapped deployment on the strength of this paragraph — ask, and the answer will be a measurement rather than a design.

For what an air-gapped install looks like today on the parts that are built, see packages.

What is built, what is exercised, and what is therefore not proven

capability	exists	exercised	what is therefore not proven
Work dispatched over SSH to a machine reachable only on the overlay	yes	yes	Nothing about performance over a relayed path. A run that works is not a run that is fast.
Membership on the network kept separate from admission to the fleet, with a stranger dispatched nothing	yes	yes	—
Per-machine readback, with each of the four absences named rather than blank	yes	yes	That the four states cover every way a machine can have nothing to report. They are the four that have been met.
Telemetry to the provider disabled at install, and the posture read back	yes	yes	That a third-party client honours its own setting on every code path. We set it and we read it; we do not inspect the client.
Minting a joining credential from the product	no — DESIGNED	no	Every unattended-provisioning flow that would depend on it.
A coordination service you host yourself, for an air-gapped fleet	DESIGNED	no	All of it, including whether the readbacks above still answer.

⛔ Two things this page does not do. It does not rank one overlay provider against another — a supported list is a list, and a ranking is not something this documentation publishes. And it does not tell you whether an overlay is the right answer for your network; that is a decision for whoever owns your network boundary, and the honest input we can give them is the table above.