Joining a host

Putting a machine into your fleet, Linux or Mac

A host is any machine that runs VMs for you. Joining is one command per machine, whichever plane it reports to: the console prints a one-shot join blob, the agent dials out with it, and the host comes online. Nothing listens for an inbound connection, so a machine behind NAT needs no open ports.

Where the console lives differs. On the hosted service it is https://console.eitri.sh (quickstart); on your own plane it is your server (self-hosting), and the join command comes from your own + Add host.

Join a Linux host

On the machine that will serve VMs—Linux with KVM (ls -l /dev/kvm)—download and verify the host bundle:

curl -fsSLO https://eitri.sh/dl/latest/SHA256SUMS
V=$(sed -n 's/.*eitri-server_\(v[^_]*\)_linux_amd64\.tar\.gz$/\1/p' SHA256SUMS)
curl -fsSLO "https://eitri.sh/dl/latest/eitri-server_${V}_linux_amd64.tar.gz"
sha256sum -c SHA256SUMS --ignore-missing
tar xzf "eitri-server_${V}_linux_amd64.tar.gz" && cd "eitri-server_${V}_linux_amd64"

/dl/latest/ is the current release. Its filenames carry the version, so SHA256SUMS—which you need to verify anyway—is where you read it from.

The Linux host bundle is named for the eitri-server it also carries: a box that only runs VMs installs the eitri-agent inside it and nothing else. On an arm64 host, _arm64 replaces _amd64 throughout.

Then click + Add host in the console and run the command it prints from the unpacked bundle—it installs the agent and joins this machine to your tenant:

sudo install -m 0755 eitri-agent /usr/local/bin/eitri-agent
sudo install -m 0644 eitri-agent.service /etc/systemd/system/eitri-agent.service
sudo eitri-agent --state-dir /var/lib/eitri-agent join eitri_join_<blob-from-console>
sudo systemctl daemon-reload
sudo systemctl enable --now eitri-agent

The agent dials out—a machine behind NAT needs no open ports. It goes online in the console within seconds.

Join a Mac

A Mac joins the same way, with two differences. It runs guests through vfkit on Apple's Virtualization.framework, and you install that yourself:

brew install vfkit

Homebrew's is the copy to use. Without vfkit, VMs placed on this host fail at once, saying so; the agent installs cloud-hypervisor for you on Linux, but it cannot install this.

Take the darwin bundle instead of the linux one: eitri-agent_<version>_darwin_arm64.tar.gz, the agent and its LaunchAgent installer, no server. macOS ships no sha256sum, so shasum checks the one line of SHA256SUMS that names it:

curl -fsSLO https://eitri.sh/dl/latest/SHA256SUMS
V=$(sed -n 's/.*eitri-agent_\(v[^_]*\)_darwin_arm64\.tar\.gz$/\1/p' SHA256SUMS)
curl -fsSLO "https://eitri.sh/dl/latest/eitri-agent_${V}_darwin_arm64.tar.gz"
grep " eitri-agent_${V}_darwin_arm64.tar.gz$" SHA256SUMS | shasum -a 256 -c -
tar xzf "eitri-agent_${V}_darwin_arm64.tar.gz" && cd "eitri-agent_${V}_darwin_arm64"

Nothing here needs sudo, and nothing goes in a system directory:

mkdir -p ~/.local/bin && cp eitri-agent ~/.local/bin/
~/.local/bin/eitri-agent join eitri_join_<blob-from-console>
./eitri-agent-launchagent.sh install ~/.local/bin/eitri-agent

State lands in ~/.eitri/agent, logs in ~/Library/Logs/eitri-agent.log, and the agent starts with your session.

The agent dials its guests over vmnet, and macOS gates local-network dialing per app: the agent needs the Local Network permission. Run from a terminal, the agent is prompted for it; installed as a LaunchAgent, it may never be. Grant it under System Settings → Privacy & Security → Local Network. Without it, guests boot and take a vmnet lease but stay unreachable through the gate—eitri ssh fails with "cannot reach VM".

Keep the binary somewhere this account owns—the agent replaces it in place when it upgrades, and the installer refuses a root-owned prefix like /usr/local/bin rather than leave you unable to upgrade.

What a Mac host does differently