vantage-docs/docs/getting-started/first-server.md

id, title, sidebar_label

id	title	sidebar_label
first-server	Add your first server	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:

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

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:

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
• Run a workflow
• Claim a Free licence