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. 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. :::

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:

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:

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, heartbeat, report inventory, run workflow steps, serve the browser console, check and apply OS updates, and report workloads (services and containers). Managing authorized_keys is a Linux-only feature, and so is package inventory and CVE scanning — the vulnerability feeds this project uses carry no Windows data. :::

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:

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
• Run a workflow
• Watch something with a monitor