# Set up a Linux host

Install and approve a dedicated Linux host, then check its runner readiness.

Use a dedicated Linux host to run jobs in disposable Docker containers. For a separate VM
per job, follow [Proxmox runners](https://mirageci.com/docs/proxmox.md) instead.

## 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](https://mirageci.com/docs/connect-github.md) first.

> **Warning: Choose the isolation boundary.**
>
> The Docker runtime needs nested-container support, such as an installed `sysbox-runc`
> runtime. Without it, setup asks whether to use privileged containers. Those containers
> have root-equivalent access to the host: use them only on a dedicated machine running
> trusted code. See [Job isolation](https://mirageci.com/docs/security.md#untrusted-jobs) before choosing.

## Install and approve

On the host, run:

Linux host · install and pair:

```bash
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](https://mirageci.com/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](https://mirageci.com/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](https://mirageci.com/runs).

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

Linux host · inspect the service:

```bash
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:

Linux host · restart after a configuration change:

```bash
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](https://mirageci.com/docs/installations.md) 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.