---
id: first-server
title: Add your first server
sidebar_label: Add your first server
---

Enrolling a server means running one command on it. The control plane issues a
short-lived token, the install script fetches the agent and writes a config, and
the machine registers itself.

## 1. Create the enrolment

In the UI, go to **Servers → Add server** Then click the **Generate Install Command** button.
This generates a server ID and a pre-registration token

:::warning The token is single-use and lives one hour
It is the only credential in the flow, and it is spent the moment the agent registers.
:::

## 2. Run the one-liner

### Linux

Run the generated install script as root.

Here is an example of the install script:

```bash
curl -fsSL "https://vantage.example.com/install?server_id=<id>&token=<token>" | bash
```

What the script does:

1. Detects architecture `x86_64` and `aarch64` only; anything else exits.
2. Downloads the binary and `checksums.txt`, and **verifies the SHA-256**, aborting on a mismatch.
3. Installs to `/usr/local/bin/vantage-agent`, mode `0755`.
4. Writes the config file at `/etc/vantage/config.yaml`
    1. This contains the server ID, the pre-registration token and the gRPC host.
5. Writes the systemd service file `/etc/systemd/system/vantage-agent.service` and starts the agent.

### Windows

```powershell
irm "https://vantage.example.com/install.ps1?server_id=<id>&token=<token>" | iex
```

Run from an elevated PowerShell.

What the script does:

1. Creates the config at `%ProgramData%\vantage\config.yaml`.
    1. This contains the server ID, the pre-registration token and the gRPC host.
2. Downloads the agent MSI from Gitea.
3. Installs the MSI and creates the Windows service.
4. Starts the agent.

:::info Windows agents do **not** manage `authorized_keys` as this is a Linux-only function.
:::

## 3. Watch it come up

The server appears immediately as `pending`. Within one poll interval, 30 seconds it becomes `active`.

Check the systemd logs using the following commands:

```bash
systemctl status vantage-agent
journalctl -u vantage-agent -f
```

## 4. Confirm it works

Open the server's detail page. Within a minute or two you should see:

- Status `active`, with a recent last-seen timestamp.
- Inventory CPU, memory, swap, partitions, kernel. Metrics refresh every 30
  seconds; the full static snapshot every 15 minutes.
- Pending OS updates, checked hourly.

## If it does not appear

| Symptom                                    | Cause                                                                                                                             |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| Script exits at "Unsupported architecture" | Not amd64 or arm64                                                                                                                |
| "Checksum mismatch!"                       | Interrupted download, or a proxy rewriting the body. Re-run                                                                       |
| "Could not determine latest agent version" | The host cannot reach `gitea.hostxtra.co.uk`, or no `agent/v*` release exists                                                     |
| Service runs, server stays `pending`       | The machine cannot reach `GRPC_HOST`. Test it from that machine                                                                   |
| Registers once then goes `offline`         | Reachable for `Register` but not for the poll usually a firewall that permits the initial connection but drops the long-lived one |

A server is marked `offline` when its last-seen time passes the threshold; that
sweep runs every two minutes, so allow for it before concluding anything.

## Next Steps

- [Assign an SSH key](../vantage/ssh-keys.md)
- [Run a workflow](../vantage/workflows.md)
- [Claim a Free licence](./claim-free-licence.md)