CroustyPatch
MenuAdd and manage agents

User guide / Get started

Add and manage agents

Enrol machines, choose push or pull, understand the files and commands on the host.

The Add agent wizard

Open it from the sidebar, the Hosts page, the Agent tokens page or the command palette. It has three steps:

  1. Choose the communication mode, the group, the environment and the optional modules.
  2. Copy the one-liner (curl or wget, or manual steps). The wizard lists the platforms this server can serve and shows a live waiting for the agent line.
  3. Once the agent connects, it confirms and links to the new host.
sh
curl -fsSL https://patch.example.com/api/v1/agent/install.sh | sudo env CROUSTYPATCH_ENROLL_TOKEN=cpt_xxxxxxxx sh

The script is generated by the server for its own address. It downloads the right binary, verifies its SHA-256 (and refuses on a mismatch), installs /usr/local/bin/croustypatch-agent, enrols with the one-time token and registers a service (systemd). Run it again and it upgrades the binary and keeps the enrolment. You can read the script first at /api/v1/agent/install.sh.

Installer options

Set these as environment variables on the same command.

VariableEffect
CROUSTYPATCH_MODE=pull|pushPersistent tunnel (default) or periodic HTTPS
CROUSTYPATCH_CA_FILE=/path/ca.pemTrust a private CA or a self-signed server certificate
CROUSTYPATCH_FORCE=1Enrol again even if already enrolled (implied when a token is given)
CROUSTYPATCH_DRY_RUN=1Install an agent that only logs what it would do

Push or pull?

  • Pull (default): the agent opens a persistent, encrypted WebSocket to the server. The server can send an order instantly (a critical patch, a scan) and the agent never exposes a port.
  • Push: the agent sends its telemetry and inventory on a fixed schedule over HTTPS. Simpler where WebSockets are awkward.

Both are TLS 1.3 only. See Communication for the details.

Platforms

The server offers the agent binaries found in its agent directories, named croustypatch-agent-<platform>: linux-x86_64 and linux-aarch64. The wizard shows which are available. The Docker image contains the one matching its own architecture; to offer the other one without rebuilding, copy it into the persisted data volume:

sh
docker cp croustypatch-agent-linux-aarch64 croustypatch-server-1:/var/lib/croustypatch/agents/

Package managers

aptpacman
Security flagorigin contains "security"only with arch-audit installed
CVE idsnot availablewith arch-audit
Selective updateyesno: always a full -Syu (Arch forbids partial upgrades)
Restore pointversion pins; refuses if the old version cannot be fetchedpins plus package files in the cache
Reboot detection/var/run/reboot-requiredrunning kernel's modules missing

On the host

  • Config: /etc/croustypatch/agent.toml.
  • State: /var/lib/croustypatch: identity key (mode 600), restore points, evidence.
  • croustypatch-agent scan prints the inventory as JSON without a server.
  • croustypatch-agent run --dry-run logs what it would do and changes nothing.
  • croustypatch-agent doctor rehearses the safety checks of a patch run and prints which packages could not be restored (OK or NOT SAFE). Run it as root to find out why a patch would be refused.

Configuration keys: server_url, mode, tls_ca_file, heartbeat_secs, eco_heartbeat_secs, eco_enabled, dry_run, package_manager (auto, apt, pacman), inventory_interval_secs, probe_interval_secs.

The agent's service has no systemd sandboxing on purpose. Package scripts install kernel modules, rebuild the initramfs and switch users, and fail half-way under those options, rollback included. Before every patch the agent checks that it is not sandboxed and refuses, changing nothing, if it is.

Re-enrolling and updating

  • Deleted a host in the web interface? Run the installer with a token again: the server has forgotten the old identity and refuses it (the agent logs "the server refuses this agent's identity (401)").
  • The host page shows the agent's version next to the server's and offers Update agent (permission hosts:write) when they differ. The agent downloads the build, checks its hash, makes sure the new binary starts, swaps it and restarts. Any failure leaves the running binary untouched.

Agent tokens

Agent tokens lists the enrolment tokens: each is stored hashed, shown once, limited in uses and lifetime, and can be revoked.