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

The fleet. Every managed machine runs an agent that connects outbound to the
control plane, and everything else in Vantage keys, workflows, monitors,
consoles targets 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. That delay is intentional a single
missed poll is not an outage.

## Tags

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

There is no tag library to manage first. A tag exists because a server carries
it, and it stops existing 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 tags
Vantage may derive from inventory later, so a tag you write today can never
collide with one invented for you tomorrow.

Anything outside those rules is refused with a message naming the rule, rather
than quietly saved in a shape you did not intend. Uppercase is not folded to
lowercase for you `Env` is a mistake, not a synonym for `env`.

### Editing a server's tags

On the server detail page, **Edit** beside the tag chips. Saving replaces the
whole set: what you see in the editor is exactly what the server will have.
There is no per-tag merge, so if two people edit the same server at once, the
last save wins outright rather than producing a blend of the two.

### Filtering the fleet

The **Servers** list has a picker per tag key in use. Choosing values from more
than one key narrows the list a server must match **all** of them, not any.
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. From the
server page you can:

- **Apply updates** pushes `ApplyUpdatesCmd` down the command stream. The
  agent runs the platform's package manager and reports back.
- **Update agent** pushes `UpdateAgentCmd` with a target version; the agent
  downloads the release, verifies it and replaces itself. See
  [Agent updates](../operations/agent-updates.md).

:::warning Applying updates is not scheduled or staged
It runs now, on that machine. If you need ordering, health gates or a canary,
build it as a [workflow](./workflows.md) instead that is what workflows exist
for.
:::

### Console

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

## Windows servers

Windows agents register, heartbeat, run workflow steps and report inventory.
They do not manage `authorized_keys` the poll loop stops after the heartbeat
on any non-Linux host. This is a deliberate scope decision, not a gap being
worked on.

## 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. The control plane stores only its SHA-256; the
plaintext exists in the agent's `0600` config and nowhere else. There is no way
to read a token back out of the control plane if one is lost, re-enrol the
machine.