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 machine 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. That calls POST /api/servers/new, which generates a server ID and a pre-registration token and hands back a ready one-liner.

:::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 calls Register. If you paste it somewhere and come back tomorrow, create a new enrolment instead — nothing is lost by doing so. :::

2. Run the one-liner

Linux

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

Run it as root. The script:

1. Detects architecture — x86_64 and aarch64 only; anything else exits.
2. Asks the Gitea API for the newest agent/v* release.
3. Downloads the binary and checksums.txt, and verifies the SHA-256, aborting on a mismatch.
4. Installs to /usr/local/bin/vantage-agent, mode 0755.
5. Writes /etc/vantage/config.yaml (directory 0700, file 0600) containing the server ID, the pre-registration token and the gRPC host.
6. Writes /etc/systemd/system/vantage-agent.service with Restart=always, and runs systemctl enable --now vantage-agent.

Windows

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

Run from an elevated PowerShell. The agent is registered as a service through NSSM, with the config at %ProgramData%\vantage\config.yaml. There is also an MSI built by CI if you would rather deploy that.

:::info Windows agents are second-class on purpose They register, heartbeat, run workflow steps and report inventory. They do not manage authorized_keys — the key subsystem is Linux-only, and a Windows agent stops after the heartbeat portion of the poll. :::

3. Watch it come up

The server appears immediately as pending. Within one poll interval — 30 seconds — it flips to active.

On the machine:

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

What happens on that first run:

1. Load /etc/vantage/config.yaml
2. pre_reg_token present  → Register() → save agent_token, clear pre_reg_token
3. Reconnect with the permanent token
4. Start: command stream · hourly update check · inventory · monitors
5. Enter the SyncKeys poll loop

After registration the config no longer contains the pre-registration token; it contains a permanent agent token instead. The control plane stores only the SHA-256 of that token, never the token itself.

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

• Assign an SSH key
• Run a workflow
• Claim a Free licence