Repair the agent
Fix an unreachable server in Servor by repairing or reinstalling the agent from the top bar or server settings — get back to a connected, green status fast.
When a server shows unreachable, its agent has stopped talking to Servor. This page explains what that state means and how to bring the server back to connected by repairing or reinstalling the agent — usually in under a minute.
What "unreachable" means
Everything you do day-to-day — the web terminal, running commands, and live resource metrics — travels through the agent installed on the server, not through SSH. So when the agent stops responding, Servor marks the server unreachable even if the machine is otherwise fine and you can still SSH into it.
Common reasons the agent goes quiet:
- The server was rebooted and the agent service didn't come back up.
- The agent process crashed or was stopped.
- The machine lost outbound internet access (the agent connects out to Servor).
- The agent was uninstalled or its files were removed.
Unreachable is about the agent, not the box
A server can be perfectly healthy and still show unreachable — it only means Servor can't reach the agent. If SSH works but the server is unreachable in Servor, repairing the agent is the fix, not reaching for SSH.
Repair from the top bar
When one of your servers goes unreachable, Servor surfaces it in the top bar so you can act without hunting through your list.
Open the alert in the top bar
An unreachable server shows up in the top bar. Click it to open the repair prompt for that server.
Choose Repair the agent
Servor gives you a fresh install command — the same one-line command used when you first added the server. Copy it.
Run it on the server
Paste the command into a shell on the machine and run it. The installer replaces the agent with a clean build and restarts the service. It's safe to run over an existing install.
Watch it reconnect
Within a few seconds the server flips back to connected with a green status.
Repair from server settings
You can also repair from the server's own settings — handy if you're already on the server page.
Open server settings
In your servers, open the server, then click the gear icon to open settings. You'll find server info, surveillance thresholds, agent repair and delete here.
Choose Repair the agent
In the agent section, choose Repair the agent to get the reinstall command.
Run the command and wait
Run it on the machine as above. The server reconnects on its own once the agent is back up.
Reinstalling is safe
The install command is idempotent — running it again on a machine that already had the agent simply repairs it. You won't lose the server, its history, or its monitors.
An agent that stops updating
The agent updates itself: a new version is picked up in under a minute, and it restarts as soon as no command or terminal is running. If it is still on an older version 30 minutes after the release, the server page shows a The agent isn't updating itself banner, with the installed and the available versions.
The old version keeps working — monitoring, terminal and commands are all still available — so it can install the new one itself.
Click Update the agent and confirm
Admins only, on Linux servers. Your vault must be unlocked: the update is a signed command, like every other one. The agent restarts without waiting to be idle, so open terminals and running commands on the server are cut — hence the confirmation.
The binary is checked before it is installed
Your browser checks that the binary is signed by Servor's release key — the same
check the agent makes when it updates on its own, no more and no less — then signs
a command that only replaces the agent if the downloaded file matches that exact
build. The previous binary is kept next to it, as
/opt/servor-agent/servor-agent.prev.
The agent restarts on the new version
The banner goes away once the agent reconnects, within seconds. The command shows up in the command history and the audit log.
On Windows, or when the update fails (a user without passwordless sudo, a machine
without systemd…), use Repair agent in the same banner.
An email after a day
If agents stay behind for more than 24 hours, the team's admins and owner get a single email listing every affected server. Each stuck agent is reported once, and only again if it gets stuck after having caught up.
When repairing isn't enough
If the agent reconnects and then drops again, or never comes back after reinstalling, the problem is usually on the machine or network side:
- Rebooted often? Make sure the agent service is enabled to start on boot (the installer sets this up; a custom-hardened box may block it).
- No outbound access? The agent needs to reach Servor over the internet. Check firewalls and egress rules.
- Firewall or SSH bootstrap trouble? Work through Connection issues for the full checklist.
Read the agent's journal
The agent logs into its own journal namespace, so that a logging loop can never evict the rest of the machine's journals. The catch is worth knowing: the usual command shows none of it.
# What everyone types — and it returns systemd's lines only:
journalctl -u servor-agent
# What shows the agent itself:
journalctl --namespace=servor -u servor-agent -n 100
journalctl --namespace=servor -u servor-agent -f # liveThe exact command is also in the unit description, so systemctl status servor-agent prints it on the first line. On a host running systemd older than
245 there is no namespace and journalctl -u servor-agent is enough.
What to look for when the terminal is unreachable:
tunnel authenticated— the tunnel is up; the problem lies elsewhere.tunnel heartbeat timed out — reconnecting— the channel died and the agent is taking it back on its own.tunnel down for 120s — 12 attempt(s), still retrying— it keeps trying without success: check outbound WebSocket access to Servor.tunnel flapped … pausing reconnects— two agents share one server. Reinstall the agent on a single host.