How the agent works

The agent is a small Go binary that runs on each server you connect. Everything CloudPilot does to a machine, it does by asking the agent.

What gets installed#

The install command sets up:

• A cloudpilot system user.
• The agent binary under /opt/cloudpilot-agent.
• A systemd service that starts the agent at boot.

It does not install a web server, a database, or a runtime. Those arrive when a project needs them.

How it talks to the panel#

The agent dials out to the CloudPilot API and holds that connection open. It does not listen on a public port, and you do not need to open one in your firewall for CloudPilot itself.

That direction matters for two reasons:

• A server behind NAT, or with every inbound port closed, still works.
• There is no CloudPilot port on your box for anyone else to find.

What it reports#

While connected, the agent sends system metrics — CPU, memory, disk — which is what fills the graphs on the server's Overview tab and what resource alerts are measured against.

What it will do#

The agent carries out instructions from the API: deploy a release, restart a service, create a database, apply a firewall rule, stream logs, open a shell. Each instruction is checked against the requesting user's permissions before it is sent, and recorded in the audit log afterwards.

If the agent stops#

The server shows as offline in the panel. What that does and does not mean:

• Your sites stay up. Nginx, your app and your database are not the agent, and they keep serving.
• You lose panel control of that machine until it reconnects — no deploys, no log streaming, no shell.
• Metrics stop. The graphs will show a gap for the period.

To bring it back, SSH in and check the service:

sudo systemctl status cloudpilot-agent
sudo systemctl restart cloudpilot-agent
sudo journalctl -u cloudpilot-agent -n 50 --no-pager

Removing it#

Removing the agent disconnects the server from CloudPilot and leaves everything else untouched — your projects, data and configuration stay exactly where they are. Deleting a server from the panel does not by itself wipe the machine; see Deleting a project for what does and does not get removed.