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

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

:::info You need a licence first
An unlicensed install is read-only, so **Add server** will be refused until a
licence is in place. If you have not done that yet, start with
[Claim a Free licence](./claim-free-licence.md).
:::

## 1. Create the enrolment

Go to **Servers → Add server**, then click **Generate install command**. Vantage
creates a server record and an enrolment token for it.

:::warning The token is single-use and lasts one hour
It is the only credential in the flow, and it is spent the moment the agent
registers. If it expires, generate a new command rather than reusing the old one.
:::

## 2. Run the one-liner

### Linux

Run the generated command as root. It looks like this:

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

The script:

1. Checks the architecture. Only `x86_64` and `aarch64` are supported.
2. Downloads the agent and verifies its SHA-256 checksum, stopping on a mismatch.
3. Installs the agent to `/usr/local/bin/vantage-agent`.
4. Writes `/etc/vantage/config.yaml` with the server ID, the enrolment token and
   the address the agent connects to.
5. Installs and starts the `vantage-agent` systemd service.

### Windows

Run this from an elevated PowerShell prompt:

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

It writes the config to `%ProgramData%\vantage\config.yaml`, installs the agent
as a Windows service and starts it.

:::info Windows servers do not get SSH key management
Windows agents register, report inventory and run workflow steps. Managing
`authorized_keys` is a Linux-only feature.
:::

## 3. Watch it come up

The server appears as `pending` straight away, and becomes `active` within about
30 seconds.

On Linux you can watch the agent itself:

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

## 4. Confirm it works

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

- Status `active`, with a recent last-seen time.
- Inventory: CPU, memory, swap, partitions and kernel. Metrics refresh every 30
  seconds, and the fuller snapshot every 15 minutes.
- Any pending OS updates, which the agent checks for hourly.

## If it does not appear

| Symptom                                    | What to check                                                                                          |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| Script stops at "Unsupported architecture" | The machine is not 64-bit x86 or ARM                                                                    |
| "Checksum mismatch!"                       | An interrupted download, or a proxy rewriting the response. Run it again                                |
| "Could not determine latest agent version" | The machine cannot reach the release host, or `GITEA_HOST` is not set on your control plane             |
| Service runs, server stays `pending`       | The machine cannot reach the agent port. Test it from that machine, not from the control plane          |
| Registers, then goes `offline`             | A firewall or proxy allows the first connection but drops the long-lived one                            |
| "Server limit reached"                     | Your licence allowance is full. Raise it in Vantage HQ, or remove a server you no longer manage         |

A server is marked `offline` once it has not been seen for a while, and that
check runs every couple of minutes, so give it a moment before concluding
anything.

## Next steps

- [Assign an SSH key](../vantage/ssh-keys.md)
- [Run a workflow](../vantage/workflows.md)
- [Watch something with a monitor](../vantage/monitors.md)