---
id: servers
title: Servers
sidebar_label: Servers
---

The fleet. Every managed machine runs an agent that connects outbound to the
control plane. Keys, workflows, monitors and consoles all point at these
records.

## Enrolling a server

Covered step by step in [Add your first server](../getting-started/first-server.md).
In short: **Servers → Add server** issues a single-use, one-hour token and shows
a one-liner to run as root on the target machine.

## Lifecycle

| Status    | Meaning                                             |
| --------- | --------------------------------------------------- |
| `pending` | Enrolment created; the agent has not registered yet |
| `active`  | The agent registered and is syncing                 |
| `offline` | Last-seen passed the threshold                      |

The offline sweep runs every two minutes, so a machine that has just gone away
takes a little while to be marked as such.

## Tags

A tag is a `key:value` label you put on a server. Tags are how you say what a
machine is, such as `env:prod`, `role:web` or `team:core-infra`, so that you can
find it later and so a [workflow](./workflows.md) can target it without you
naming it by hand.

There is no tag library to set up first. A tag exists as soon as a server
carries it, and disappears when the last server carrying it drops it.

### The rules

| Rule       | Value                                             |
| ---------- | ------------------------------------------------- |
| Characters | lowercase letters, digits, `-` and `_`, on both halves |
| Key length | up to 32 characters                               |
| Value length | up to 64 characters                             |
| Per server | up to 20 tags                                     |

Neither half may be empty, and keys beginning `sys:` are reserved for Vantage's
own use.

Anything outside those rules is refused, with a message naming the rule.
Uppercase is not corrected for you, so `Env` and `env` are different tags.

### Editing a server's tags

On the server's page, click **Edit** beside the tags. Saving replaces the whole
set, so what you see in the editor is exactly what the server ends up with. If
two people edit the same server at once, the last save wins.

### Filtering the fleet

The **Servers** list has a picker per tag key in use. Choosing values from more
than one key narrows the list, because a server must match **all** of them.
Untagged servers appear only when no filter is set.

:::tip A filtered fleet view is a link
The filter lives in the URL (`/servers?tag=env:prod&tag=role:web`). Copy the
address bar and you have sent someone the same view, not a description of how to
reproduce it.
:::

## The server detail page

### Keys

Which SSH keys are assigned to this machine, and their state. See
[SSH keys](./ssh-keys.md).

### Inventory

Agents report:

| Data                                     | Refreshed        |
| ---------------------------------------- | ---------------- |
| CPU, memory, swap, load                  | every 30 seconds |
| Partitions, kernel, full static snapshot | every 15 minutes |

The two carry separate timestamps, so a stale static snapshot beside fresh
metrics is normal rather than a fault.

### OS updates

Agents check for pending package updates hourly and report the count - the
machine's own package manager on Linux, the Windows Update COM API on Windows.
From the server page you can:

- **Apply updates** runs that check's install path and reports back. The agent
  never reboots the machine; if one is owed, a **reboot required** badge
  appears on the next inventory snapshot instead.
- **Update agent** upgrades the Vantage agent on that machine. See
  [Agent updates](../operations/agent-updates.md).

:::warning Applying updates is not scheduled or staged
It runs immediately, on that machine. If you need ordering, health checks or a
test machine first, build it as a [workflow](./workflows.md) instead.
:::

### Console

Opens a browser SSH, RDP or VNC session. See [Browser console](./browser-console.md).

## Windows servers

Windows agents register, heartbeat, run workflow steps, report inventory,
check and apply OS updates, report workloads (services and containers), and
serve the browser console. They do not manage `authorized_keys`, and they are
not covered by package inventory or CVE scanning - the vulnerability feeds
this project uses carry no Windows data.

## Removing a server

Deleting the server record removes it from the fleet. It does **not** uninstall
the agent, which will keep trying to sync and failing. Uninstall it on the
machine too:

```bash
systemctl disable --now vantage-agent
rm -f /usr/local/bin/vantage-agent /etc/systemd/system/vantage-agent.service
rm -rf /etc/vantage
systemctl daemon-reload
```

Keys previously written to `authorized_keys` stay on disk, because the agent is
no longer running to remove them. Revoke and let the agent apply the change
**before** you delete the server if that matters to you.

## Agent tokens

Each server has its own token, which exists in full only in the agent's config
file on that machine. Vantage stores a fingerprint of it and cannot show it to
you again. If a token is lost, enrol the machine again.