Docs · The agent

Connect a server from any provider.

Hetzner, AWS, DigitalOcean, a box under your desk: install the agent with one command, and the server's files, packages and services get a history you can diff, tag and roll back.

1. Get the command

In the panel: Add → Server from another provider (or Machines → Connect a server → Any Linux server). Give it a name if you like, and decide whether to allow remote changes (below; off unless you tick it). You get one line:

curl -fsSL 'https://api.computeforge.com/panel/api/agent/v1/install.sh?code=cfe_…' | sudo sh -s -- --code cfe_…

The code in it works once and expires after 60 minutes. If it expires before you use it, the panel offers a new one. From a terminal, cf machine add prints the same line, and cf connect ssh://root@203.0.113.9 runs it for you over your own SSH connection.

2. Run it on the server, as root

The installer:

  • downloads the agent for the server's architecture (amd64 or arm64);
  • checks the binary's SHA-256 against the release manifest, and the manifest's signature with OpenSSL 3 (it installs OpenSSL first if it is missing; where only OpenSSL 1.1 exists, as on Ubuntu 20.04, the manifest must be the one our portal checked), before it installs anything. If it cannot verify the release, it installs nothing;
  • installs it under /usr/local/lib/cf-agent, with its settings in /etc/cf-agent and its data in /var/lib/cf-agent;
  • adds the systemd units cf-agent.service, cf-agent-apply.socket and cf-agent-apply.service (on Alpine with OpenRC: /etc/init.d/cf-agent and cf-agent-apply);
  • connects the server to your workspace with the code, and starts the agent.

No reboot and no kernel module. The panel shows the server as soon as the agent has connected, usually within seconds.

What it records

Changes to files, packages and services, with who made them and when. Configuration files are recorded with their content; other tracked paths by their SHA-256 only. Secret files (keys, password files) are never uploaded: only the fact that they changed. You can add your own paths in the machine's Settings.

The agent records a baseline of the server when it first starts. Changes made in that first minute — before the baseline is uploaded — are not recorded.

What it may change: apply mode

By default the agent only records your server's changes (in the auto-RAM pilot it also manages memory and swap). Putting a file back, undoing a change or copying a change from another server (cf checkout, cf revert, cf cherry-pick) needs apply mode, and only root on the server can turn it on:

sudo cf-agent apply on     # signed jobs from your account may change this server
sudo cf-agent apply off    # back to recording only
sudo cf-agent apply status

Every job is signed by ComputeForge and checked again on the server before it runs. The agent itself cannot change its own apply setting.

Systems

  • Tested: Ubuntu 22.04 and 24.04, Debian 12, AlmaLinux 9, Alpine 3.22 with OpenRC (amd64).
  • Should work: Rocky Linux, Fedora, other Linux systems with systemd or OpenRC, on amd64 or arm64.
  • Arch Linux: file history works; package history does not yet.
  • Not supported: systems with neither systemd nor OpenRC, 32-bit, anything but Linux.

Price and limits

Free on every server you connect, wherever it runs. Up to 50 connected servers per organization, with 90 days of history. Per server and day (UTC) the agent records up to 20,000 changes and 100 MiB of file content in full; past that it still records each change, without its content, until the next day.

Check on it

sudo cf-agent status

Shows the machine it is, whether it is connected, apply mode, and what is waiting to be sent. In the panel, Machines lists every connected server with its last change.

Disconnect and remove

Revoke (machine → Settings, or cf machine revoke web-1) stops the agent's access within seconds; the history recorded so far is kept. To take the agent off the server:

curl -fsSL 'https://api.computeforge.com/panel/api/agent/v1/uninstall.sh' | sudo sh

It removes the agent, its settings and its units. It keeps /var/lib/cf-agent/spool (changes not yet sent) unless you add -s -- --purge after sh. The uninstaller holds no secret and installs nothing.

Related