---
title: "Manage servers"
description: "Manage registered servers in Alpacon. Edit server details, turn the tunnel and code editor on or off, restart or upgrade the agent, and review upgrade history."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Manage servers

Modify server information and control servers remotely.

## Edit server information

### Change basic information

1. Click **Update** on the server's detail page
2. You can modify:
   - **Name**: Server identifier
   - **Authorized groups**: User groups with access
   - **Owner**: Server owner
3. Click **Save**

**Note:** Metric alerts are managed in the Metrics app—see [Configure metric alerts](/use/metrics/rules/).

### Tunnel and code editor

Two checkboxes in the **Update** panel decide whether a server can be used for port forwarding and for the browser code editor:

- **Tunnel**: allows [port forwarding](/reference/work-session-features/) with `alpacon tunnel`
- **Code editor**: allows the [code editor](/use/work-sessions/editor/connect/)

In a work session, port forwarding and the code editor work only on servers where the box is checked. If no server in a session has it on, the feature in the session shows a warning that no server has it enabled.

**Who can change them:** owners and managers of a group assigned to the server, [maintainers of the server](/use/workspace/settings/roles/#permission-inheritance), and users with the Staff or Superuser role. Other users don't see the **Update** button.

**Requirements:**

| Checkbox | Requires |
| --- | --- |
| **Tunnel** | Alpamon 2.0.0 or later |
| **Code editor** | Alpamon 2.0.0 or later and at least 2 GB of memory |

If the server doesn't meet them, the feature can't be turned on: saving fails with an error that names the requirement. [Upgrading the agent](#agent-card) fixes the version requirement; it doesn't add memory, so a server with less than 2 GB can't run the code editor. If the agent later reports a version that doesn't meet the requirement, Alpacon turns the feature off, and it stays off until you turn it on again.

On Windows servers, port forwarding works with Alpamon 2.5.1 or later, but the code editor can't run: the box can be checked, but opening the editor ends with a startup timeout. See [Windows servers](/reference/platforms/windows/).

**Turning a feature off** stops new port forwarding or editor connections to the server. An open editor can't be reconnected while the feature is off.

**Defaults for new servers:** a Superuser sets whether each feature starts on for newly registered servers in [Server defaults](/use/policies/server-access/). The default applies once, when a server is registered, and only if it meets the requirements. Changing it doesn't change servers that are already registered.

### Server details

View detailed information in the server detail page:

**Overview tab:**

- Agent information (version, status)
- OS information (distribution, version)
- System information (CPU, memory, disk)
- Operating information (uptime, boot time)
- Network interfaces
- Offline alert history

Next to the last-synced time, click **Refresh now** to pull current system information immediately instead of waiting for the next scheduled sync.

Under Network interfaces, **Offline alert history** lists this server's resolved offline alerts, newest first, five per page: when each was raised (**Raised**), when it resolved (**Resolved**), how long it stood (**Stood for**), why it closed (**Cause**), and which channels delivered the resolution (**Delivered**—the same chips as [Alert history](/use/metrics/rules/#alert-history)). **Cause** shows a short label with a tooltip carrying the full sentence: **Reconnected**, **Stable again** (a flap phase settled), **Decommissioned**, **Disabled**, **Alert turned off**, **Deleted**, **Instance off**, **No longer applies**, or **Not recorded** for an alert resolved before causes were tracked. Unlike charts and metric alerts, this table isn't gated by the Metrics extension—it's available on every plan.

**Activity tab:**

- Command execution history
- Server comments and mentions
- User activity logs
- Direct logins that reached the server without Alpacon, in the same timeline as work sessions—see [On a server's page](/use/audit/governance/external-access/review/#server-page)

**Access tab:**

- **Direct-login coverage**: whether direct logins to this server are captured, and for a server that isn't covered, the reason, what to change and how to check—see [Check a server](/use/audit/governance/external-access/coverage/#check-a-server)
- System users, each with its last direct login, its open findings, and a flag when it is bound to a removed member
- System groups

Charts and metric alerts live in the Metrics app, not on server detail—see [Monitor server status](/use/servers/monitor/).

**Logs tab:**

- Recent logs from Alpamon agent
- Backhaul history (data transmission logs)
- Transmission status and data size

## Server control

**Requirements:**

- Server status: **Connected**
- Permission: owner or manager of an assigned group, a [maintainer of the server](/use/workspace/settings/roles/#permission-inheritance), or a user with the Staff or Superuser role

### Agent card

The Agent card on a server's detail page covers the Alpamon agent itself. Next to the agent's version, **Update policy** shows the workspace's [agent update policy](/use/workspace/settings/agent-updates/): **Latest**, **One release behind**, or **Manual**.

- **Restart agent**: restarts the agent process. Useful for resolving connection issues—the server briefly shows offline and reconnects on its own.
- **Upgrade agent**: updates the agent to the latest release and restarts it. Shown only when the update policy is **Manual**; under an automatic policy, the agent is upgraded inside the workspace's maintenance window and no button is shown. On Windows the agent needs Alpamon 2.4.0 or later; for an older agent, see [upgrading the agent](/use/servers/register/install/#upgrading-the-agent).
- **Install or upgrade alpamon-pam**: installs the `alpamon-pam` package on the host as root through its package manager, or upgrades an older version, for a server registered with alpamon alone or one that was offline when [sudo with MFA](/use/work-sessions/terminal/sudo-with-mfa/) was turned on. Shown for a host that uses `apt`, `yum`, or `zypper` while its agent is connected. When the server's sudo policy row shows that `alpamon-pam` isn't set up, the same action appears as an install link on that row. While **Sudo through Alpacon** is off in [Access rules](/use/policies/access-rules/), the button is disabled and shows **sudo with MFA is off in Server access policies**. A host already on the current version is left as it is, and a second request is refused while an install is still pending. The same action is available from the CLI as [`alpacon agent install-pam`](/reference/cli/agent/install-pam/).

Click the button, confirm in the dialog, and watch the result in a toast message.

An upgrade never moves an agent to an older version. Under **Manual**, when the agent already runs the latest release, **Upgrade agent** stays visible but disabled, with the note **Agent is up to date**. While an upgrade is already in progress on the server, a second request is refused with "An agent upgrade is already in progress on this server. Try again after it finishes."

### Upgrade history

On the server's **Overview** tab, after network interfaces and offline alerts, **Upgrade history** lists automatic and manual agent upgrades for this server, newest first, five per page. Page controls appear below the list when there are more than five. **Upgrade status** and **Started by** (**Automatic** or **Manual**) narrow the list. Repeated failures of the same kind appear as one row, such as "Failed 3 times in a row"; while a filter is on, each attempt has its own row. Select a failed, timed-out, or rolled-back row with a log to open its agent log. **All upgrade history** opens upgrades for every server you can see. Anyone who can see the server can see its history.

Each row shows:

- **Outcome**: **In progress**, **Succeeded**, **Rolled back** (the new version didn't come up cleanly, so the agent went back to the previous one), **Failed**, **Timed out** (the agent didn't confirm the upgrade in time), or **Refused** (the upgrade was withdrawn before it reached the agent).
- **Versions**: the version the agent moved from and the version it moved to, for example `1.4.2 → 1.5.0`. Until the agent reports back, the version it's being upgraded to is marked **(target)**.
- **When and who**: when the upgrade was requested, and who started it—a member's username, an API token's name, or **Alpacon automatic policy (latest)** for an automatic upgrade.
- **Reason**: for a failed or rolled-back upgrade, why it didn't land, and for a refused or failed one, a short explanation from Alpacon.

The reason labels are:

| Label | What it means |
|---|---|
| **Signature invalid** | The release's signature didn't verify, so the agent didn't install it |
| **Digest mismatch** | The downloaded package didn't match its published checksum |
| **Download failed** | The agent couldn't download the release |
| **Swap failed** | The agent couldn't replace its own binary with the new one |
| **Health check failed** | The new version didn't pass its health check after starting |
| **Package manager error** | The system package manager (`apt`, `yum` or `zypper`) reported an error |
| **Maintenance window closed** | The maintenance window closed before the upgrade could start |
| **Alpacon configuration issue; no action needed** | A problem on Alpacon's side. Nothing needs changing on your server |
| **Unknown error** | The agent reported a failure without a known reason |

A **Refused** row usually means the maintenance window closed before the upgrade reached the agent, the policy was switched to **Manual**, a manual upgrade replaced a pending automatic one, or Alpacon paused automatic upgrades platform-wide. Nothing was installed, and the agent keeps running the version it had.

Records begin when upgrade history was introduced. Earlier upgrades aren't shown, and a server with no upgrades since then shows "Upgrade records are kept from the time this history was introduced. Earlier upgrades are not shown." Each upgrade is also recorded in the [activity log](/use/audit/governance/activity-log/), both when it's sent and when it ends, so it's included when you search or export workspace activity.

To see upgrades across every server you can see, open Servers and choose **More** → **Agent upgrades**. It lists the latest agent upgrades on those servers, newest first, and any role that can see servers can open it. Filter it by **Outcome** or by **Started by** (**Automatic** or **Manual**), and select a server name to open that server. Each row reads the same way as the list above. The same history is also available through the [agent upgrades API](/reference/api/servers/agent-upgrades/).

### Upgrade failure alert

When an agent upgrade fails or is rolled back, Alpacon raises a **warning** alert on that server, titled for example `Agent upgrade to 1.5.0 failed`. It appears in the bell and the alert list only: no email or Slack message goes out for it, and it isn't part of the hourly open alert digest. A server has at most one of these alerts open at a time, however many upgrades fail in a row, and the next successful upgrade resolves it. A successful upgrade sends no notification, and an upgrade that fails because of **Alpacon configuration issue; no action needed** raises no alert.

### Host operations

Rebooting a server, shutting it down, or upgrading its operating system packages isn't a button on the server page. Run it inside a [work session](/use/work-sessions/) instead: open Websh in the session, or attach `alpacon exec` to it with `--work-session`, then run the command with sudo, the same way as any other privileged command (`sudo reboot`, `sudo shutdown -h now`, `sudo apt upgrade -y` or your platform's package manager). For example, `alpacon exec --work-session SESSION_ID my-server -- sudo reboot` reboots `my-server` inside the session `SESSION_ID`. That keeps the operation under your workspace's sudo policy, MFA, and approval rules, and Alpacon records the session like any other. If you're planning one, [mute the server's alerts](/use/servers/monitor/#mute-a-server) first—Alpacon doesn't hold the offline alert automatically for a command run this way.

## Server list actions

Select one or more servers on the server list to:

- Request a work session covering the selected servers (**Connect**).
- **Mute alerts** on the selected servers—see [Mute a server](/use/servers/monitor/#mute-a-server).
- **Unregister** the selected servers—see [Bulk deletion](/use/servers/remove/#bulk-deletion).

Agent restart and agent upgrade aren't available from the list; use the [Agent card](#agent-card) on each server's detail page. Refreshing system information isn't available from the list either; use **Refresh now** next to the last-synced time on the detail page.

**Filtering:**

- Group filter: Show servers from specific groups
- Status filter: Separate Connected/Disconnected servers
- Search: Quick search by server name

## Server comments

Share server-related information with team members.

**Add comment:**

1. Server detail > Activity tab
2. Write content in comment input
3. Mention specific users with @username
4. Click **Add**

**Pin comments:**

- Pin important comments to top (max 3)
- Click pin icon to pin/unpin

## Upgrade a Windows agent that cannot self-update

Automatic and manual agent upgrades are listed in [upgrade history](#upgrade-history). Linux upgrades use the host package manager; macOS and Windows download a release. The server needs outbound HTTPS to `api.github.com` to check versions. During an upgrade the agent restarts, so the server may briefly appear offline. If the upgrade fails, the previous version continues to run.

On **Windows**, an agent running Alpamon 2.4.0 or later self-updates the same way as macOS. An agent older than 2.4.0 can't update itself: its upgrade fails with **Unsupported platform** in the upgrade history, and Alpacon doesn't schedule another one until the agent reports a different version. Re-running the installer doesn't help on a registered host, because `alpamon.exe register` stops at `config file already exists`. Replace the binary by hand once instead, and later upgrades run on their own. Do the same if the self-update path is blocked.

Run these from an elevated PowerShell on the server itself (local console, RDP, or cloud serial console), not over Websh. Stopping the service ends every open Websh and WebFTP session and tunnel on the server, not only yours, so pick a time when no one is using it:

1. From [GitHub Releases](https://github.com/alpacax/alpamon/releases), download the latest `alpamon-X.Y.Z-windows-amd64.zip` and `alpamon-X.Y.Z-checksums.sha256` into the same folder. Check that the archive's hash matches the hash listed for that archive in the checksums file, and don't use the archive if they differ:

   ```powershell
   (Get-FileHash .\alpamon-X.Y.Z-windows-amd64.zip -Algorithm SHA256).Hash.ToLower()
   Select-String 'alpamon-X.Y.Z-windows-amd64.zip' .\alpamon-X.Y.Z-checksums.sha256
   ```

2. Unblock and extract the archive as in [Method 1](/use/servers/register/install/#method-1-manual-install).
3. In the extracted folder, stop the service and swap the binary. An older agent can leave an `alpamon.exe` process running after the service stops, which keeps the file locked, so end any that remain and move the old file aside instead of overwriting it:

   ```powershell
   Stop-Service alpamon -Force
   Get-Process alpamon -ErrorAction SilentlyContinue | Stop-Process -Force
   Move-Item -Force "$env:ProgramFiles\alpamon\alpamon.exe" "$env:ProgramFiles\alpamon\alpamon.exe.old"
   Copy-Item .\alpamon.exe "$env:ProgramFiles\alpamon\alpamon.exe"
   Start-Service alpamon
   ```

   The new agent deletes `alpamon.exe.old` when it starts.

4. Check that the agent version on the server's [Agent card](/use/servers/manage/#agent-card) shows the new release.

If an upgrade doesn't take effect, see [agent upgrade issues](/use/servers/troubleshooting/#agent-upgrade-issues).

## Related docs

- [Monitor servers](/use/servers/monitor/)
- [Control server access](/use/servers/groups/)
- [Remove a server](/use/servers/remove/)

Source: https://docs.alpacax.com/use/servers/manage/