Set up a Linux host

Before you start

You need an x64 or arm64 Linux host with systemd, Docker Engine, outbound HTTPS access, and root or sudo access. Setup also requires Python 3.9 or newer, curl and OpenSSL. Missing prerequisites are named before installation continues. Connect your private repositories through the Mirage GitHub App first.

Install and approve

On the host, run:

bash <(curl -fsSL https://mirageci.com/bootstrap/linux)

Setup verifies and installs the signed Mirage agent, checks Docker, and asks about its isolation runtime. It then prints an approval link and a verification code.

1. Open the approval link in your browser and sign in to Mirage.
2. Check that the displayed code matches your terminal.
3. Choose the account that will manage this host, then confirm.
4. Return to the terminal. Setup finishes pairing and starts the systemd service.

An expired request needs a new setup attempt. Running setup again keeps the host’s existing configuration and pairing, so a failed attempt can be retried.

Check readiness and route a job

Open Machines in the account you chose. Confirm that the host is connected and its Linux profile reports Ready. An x64 host runs Linux x64 jobs; an arm64 host runs Linux arm64 jobs.

Open Repos, choose a repository, then select Set up routing. The readiness check names the machine types your chosen jobs need. Review and merge the setup pull request on GitHub, then follow the first job in Runs.

If the machine does not become ready, inspect its service logs on the host:

sudo systemctl status mirage-linux-agent
sudo journalctl -u mirage-linux-agent -n 80 --no-pager

Updates and availability

The installed service updates through signed Mirage releases. Host settings live in /etc/mirage/agent.env; after editing them, restart the service:

sudo systemctl restart mirage-linux-agent

To stop accepting work temporarily, pause the machine in Mirage. Before permanently removing capacity, make sure its workflows have a working fallback or restore their previous runner labels. Accounts and teams explains sharing.

To remove the host from the fleet, open its machine page and choose Delete machine…. Its personal controller or an organization owner can confirm deletion. Mirage revokes pairing and sharing access; past run history is kept. Active work on a connected host must finish first; jobs on an unreachable host may be interrupted. The agent stays installed on the host. Pair it again to add it back.