Add devices to the mesh

What a mesh is

A mesh is a private, encrypted overlay between outposts. One outpost per mesh is the authority: it holds the mesh’s certificate authority, mints invitations, gives each member a fixed mesh address and keeps the blocklist. A lighthouse is a member others can dial at a public address; it also relays traffic between members that cannot reach each other directly. Every other member is a client: it needs no public address and reaches peers through the lighthouses, though it may also publish direct addresses that peers dial.

Membership is what lets outposts run each other’s work: members accept calls from the outposts their authority enrolled and has not revoked, and nobody else. An outpost belongs to one mesh at a time; joining another leaves the first. Joining moves no application data.

Before you start

• You are an administrator on the inviting outpost. Settings → Mesh is hidden from other roles.
• Both outposts are installed and started (drkm start).
• The mesh authority’s HTTPS address, its --public-url, is reachable from the new machine. The invitation carries that address even when it was minted on another member; the join is redeemed there and refreshes are pulled from it.
• A machine that others should reach directly, a lighthouse, is dialable on UDP port 4242 or the port it declares. Clients need no reachable address.

Create your mesh

A fresh outpost belongs to no mesh. In Settings → Mesh, the Mesh networking switch opens the Create a mesh dialog: name it, and this outpost becomes the authority of a one-member mesh. No restart is needed. For a machine other outposts should dial, give it a reachable address when you start it.

# Declare the HTTPS origin and the UDP endpoint other outposts can reach
drkm start --public-url https://outpost.example --nebula-advertise 203.0.113.10:4242

Add a second machine

On any enrolled outpost, choose Add outpost in Settings → Mesh → Outposts or on the Outposts page. It mints a single-use invitation code, valid for 24 hours, shows it once with a Copy button, and then waits. On the new machine, either paste the code into Settings → Mesh → Settings → Join and press Join mesh, or run drkm enroll and paste it at the hidden prompt. The new outpost generates its keys locally, the authority assigns its mesh address and signs its certificates, and the tunnel comes up.

The same two steps work from the terminal. Invitations cannot be revoked; they expire, and a retry with the same code returns the same assignment.

# On any enrolled outpost, as an administrator
drkm enrollment invite --url https://outpost.example

# On the new machine, with its outpost running
drkm enroll
# Enrollment code: <paste the drkm1.… code>

# Unattended
DRKM_ENROLLMENT_TOKEN='drkm1.…' drkm enroll

See it arrive

The Add outpost dialog reads Enrolled: name as soon as the new outpost’s first heartbeat lands, within about a minute. After that heartbeat it appears under Settings → Mesh → Outposts, on the Outposts page, in drkm console outposts and in drkm.outposts(). Opening it there shows its roles, mesh address, dial address, enrollment time and last heartbeat, and offers Rename, Configure network and Remove from mesh.

Lighthouses and addresses

Make an outpost a lighthouse from its entry under Settings → Mesh → Outposts: Configure network, then add up to 16 host and port rows it can be dialed at. The Lighthouses tab shows the phone book every member pulls and a health line: with none, only known direct addresses can connect; with one, losing it leaves only direct addresses; with two or more, losing one is fine. Two lighthouses is the minimum for a mesh that must survive losing a machine.

If the authority is down, existing tunnels keep working; joins, renewals and blocklist pulls wait until it returns. Host certificates are signed for 10 years, so certificate expiry is not an availability concern.

Remove, leave, restore

Remove from mesh on an outpost’s entry, or drkm enrollment remove, blocks every certificate the authority issued to it; peers stop trusting it at their next refresh, and the removed outpost learns at its own next refresh, turns its mesh off and keeps its identity, keys and data. A new invitation brings it back with the same mesh address, and the authority’s Blocked outposts list offers Restore.

An outpost leaves on its own from Settings → Mesh → Settings → Leave mesh or with drkm enrollment leave; leaving needs the authority reachable; otherwise it is refused and the outpost stays a member. An authority never leaves its own mesh: it removes members one at a time, or Delete mesh removes everyone at once and turns its mesh off. To merge a whole mesh into another, the adopting side mints an ordinary invitation and the adopted authority joins with Bring them along or drkm enroll --bring-mesh; each of its outposts follows at its next refresh.

drkm enrollment remove <outpost-id> --url https://outpost.example
drkm enrollment leave --url https://this-outpost.example
drkm enroll --bring-mesh

Keep the fleet up to date

Each outpost follows published releases itself; nothing is pushed from the authority. Administrators see an update icon at the bottom of the console sidebar, with a red dot when a newer release is out, and Settings → Updates offers Check for updates, Update now, Automatic updates and Alpha releases. On the host, drkm update does the same and redeploys a running outpost. Automatic updates run once a day unless turned off, restart the outpost, and roll back if the new release never becomes healthy.