TidyWipe Server Agent 0.2.1 · preview
Server Agent installation guide
The Server Agent is a small program for Linux servers. It reports the server's health (CPU, memory, disks, services) to your TidyWipe dashboard and the desktop app, and lets you run a read-only Remote Scan that shows what could be cleaned. This guide takes you from download to your first scan. Every command can be copied with the button on its right.
Remote deletion and automatic cleanup are off
1.Supported Linux distributions
Any 64-bit Linux server that uses systemd, on x86_64 (amd64) or arm64 (aarch64). The agent is a single static program with no dependencies.
- Tested: Ubuntu 24.04 LTS.
- Expected to work (not yet tested): Ubuntu 22.04, Debian 12, RHEL / AlmaLinux / Rocky Linux 9, Fedora.
- Package caches are recognised for
aptanddnf; other package managers are reported as unsupported. - Not supported: systems without systemd, 32-bit systems, macOS and Windows servers.
2.Minimum server requirements
- Access: a user who can run
sudo(root is needed to install the service). - Memory: the service typically uses around 15 MB and is capped at 128 MB.
- CPU: negligible; capped at 20% of one core.
- Disk: about 10 MB for the program, plus a few MB of local history.
- Network: outbound HTTPS (port 443) to
api.tidywipe.online. No inbound port is opened. - Account: a TidyWipe account to connect the server to (free accounts can connect servers).
3.Download the agent
One archive contains both the x86_64 and the arm64 program; the installer picks the right one. Run these commands on the server:
cd ~ curl -fLO https://tidywipe.online/downloads/server-agent/tidywipe-agent-0.2.1-linux.tar.gz echo "90161204ba958f7ab5b1b28212ca7aa6a82a6ef9cce21c7b38969a11d3620fd0 tidywipe-agent-0.2.1-linux.tar.gz" | sha256sum -c -
The last command must print tidywipe-agent-0.2.1-linux.tar.gz: OK. If it says FAILED, delete the file and download it again. The checksum is also shown on the download page.
Then unpack it and check every file inside:
tar -xzf tidywipe-agent-0.2.1-linux.tar.gz cd 0.2.1 sha256sum -c SHA256SUMS
4.Install the agent
From the unpacked 0.2.1 folder:
sudo ./install.sh
The installer checks the program against SHA256SUMS (and refuses to install if it doesn't match), then creates the unprivileged system user tidywipe-agent, installs /usr/local/bin/tidywipe, writes the configuration/etc/tidywipe-agent/config.yaml (an existing one is kept), and installs and starts the tidywipe-agent service.
To see what it would do without changing anything, run ./install.sh --dry-run first. There is no curl | sh installer, by design.
5.Connect the server to your TidyWipe account
- Sign in at tidywipe.online → Dashboard → Servers and choose Add server.
- TidyWipe shows a one-time enrollment token and a command. Copy the command (it contains no secret).
- Run the command on the server. It looks like this:
read -rs -p 'Enrollment token: ' TW_TOKEN; echo; printf '%s\n' "$TW_TOKEN" | sudo tidywipe connect --api https://api.tidywipe.online --token -; unset TW_TOKEN
- At the hidden
Enrollment token:prompt, paste the token and press Enter. Nothing is shown while you paste; that's expected. - Within about two minutes the server appears as online under Dashboard → Servers, and in the desktop app under Servers.
The agent swaps the token for its own server credential, stored in /var/lib/tidywipe-agent/credential (readable only by the agent). No restart is needed.
6.Using an enrollment token securely
- A token works once and expires (after 1 hour by default). Only its hash is stored by TidyWipe; it is shown to you once.
- Don't paste the token into chat, tickets, scripts or the command line itself. The command above reads it from a hidden prompt, so it never appears in your shell history or the process list.
- Unused tokens are listed under Dashboard → Servers → Enrollment tokens. Revoke any you no longer need.
- If a token may have leaked before it was used, revoke it and create a new one.
- Never share
/var/lib/tidywipe-agent/credential. If a server is compromised, disconnect it in the dashboard; its credential stops working at once.
7.Starting and enabling the systemd service
The installer already enables and starts the service. These commands do it by hand, and make sure it starts at boot:
sudo systemctl enable --now tidywipe-agent systemctl is-enabled tidywipe-agent systemctl is-active tidywipe-agent
Both checks should print enabled and active.
8.Checking the agent status
systemctl status tidywipe-agent sudo tidywipe agent status sudo journalctl -u tidywipe-agent -n 50
sudo tidywipe agent status shows whether the service runs, when it last collected and reported data, how many samples wait to be sent, and the connection state (connected, not connected or REVOKED). tidywipe version prints the installed version.
9.Viewing CPU, RAM and disk metrics
- Dashboard: Dashboard → Servers → your server shows status, CPU, memory, disks and failed services, with history charts.
- Desktop app: open Servers in TidyWipe 1.3 or later while signed in to the same account.
- On the server:
sudo tidywipe status sudo tidywipe health sudo tidywipe disk analyze
status gives an overview (host, CPU and load, memory and swap, filesystems, health), health lists each check with a recommendation, and disk analyze shows the largest directories and files. All three only read; sudo is needed because the configuration is readable only by root and the agent.
10.Running a Remote Scan
Remote Scan is off on a new installation. Turn it on in scan-only mode, which allows scans and previews and nothing else:
- Set
remote_cleanup.enabledtotruein the configuration (the categories list stays empty,[]):
sudo sed -i '/^remote_cleanup:/,/^[^ #]/ s/^\( enabled:\)\( *\)false/\1\2true/' /etc/tidywipe-agent/config.yaml sudo tidywipe config validate sudo tidywipe config show | grep -A4 '^remote_cleanup:'
The last command must show enabled: true and allowed_categories: []. (You can also edit the file with sudo nano /etc/tidywipe-agent/config.yaml.)
- Install the scan helper and restart the agent:
sudo tidywipe agent install --enable-remote-cleanup sudo systemctl restart tidywipe-agent
The helper is a separate root service without network access. With an empty categories list it can only scan: the agent and the helper both refuse any cleanup, and the helper has no write access to the cleanup folders.
- In Dashboard → Servers → your server (or the desktop app's Servers screen), choose Scan server. The scan is picked up within about 15 seconds and the preview appears shortly after.
You can also scan directly on the server: sudo tidywipe scan (add --all to list every item). It only reads.
To turn Remote Scan off again: sudo systemctl disable --now tidywipe-helper.path, or set enabled back to false and restart the agent.
11.Understanding scan classifications
| Classification | Meaning |
|---|---|
| SAFE_TO_CLEAN | Old rotated logs, expired temporary files, old crash dumps and similar, past their retention period. Only these could ever be cleaned. |
| REVIEW_REQUIRED | Worth a look, but not removed automatically; for example a systemd journal that is large but still within its size limit. |
| IN_USE | A running program has the file open, or a package manager is running. Skipped. |
| PROTECTED | Names and paths that must never be deleted (for example credentials or environment files). Never touched. |
| UNKNOWN | Couldn't be classified safely (for example unreadable). Never touched. |
Sizes are shown per category and in total. Active log files, files with several hard links and anything inside the retention period are never offered. Docker container logs are reported only.
12.Updating the agent
Download and verify the new archive as in step 3, then run its installer. Your configuration, history and connection are kept.
cd ~/<new version folder> sudo ./install.sh sudo systemctl restart tidywipe-agent tidywipe version
If you enabled Remote Scan, run sudo ./install.sh --enable-remote-cleanup instead, so the helper is updated too.
13.Restarting the agent
sudo systemctl restart tidywipe-agent systemctl is-active tidywipe-agent
Restart it after every change to /etc/tidywipe-agent/config.yaml. Data collected while the agent was stopped is simply missing; nothing else is lost.
14.Uninstalling the agent
First disconnect the server, so its credential is revoked in your account. Then run the uninstaller from the unpacked folder:
sudo tidywipe disconnect cd ~/0.2.1 sudo ./uninstall.sh
This removes the service, timers, helper and program, and keeps the configuration and local history. To remove those as well, together with the tidywipe-agent user:
sudo ./uninstall.sh --purge
You can also disconnect a server from Dashboard → Servers → your server → Disconnect server.
15.Troubleshooting connection problems
Start with:
sudo tidywipe agent status sudo journalctl -u tidywipe-agent -n 100 sudo tidywipe config validate
| Problem | What to do |
|---|---|
| The enrollment token is invalid, expired or already used | Tokens are single-use and expire. Create a new one under Dashboard → Servers → Add server. |
| already connected as "…" | The server already has a credential. Run sudo tidywipe disconnect, then connect again with a new token. |
| Network error, or the server stays pending / offline | Allow outbound HTTPS (443) to api.tidywipe.online and check that the service is running. Test with curl -sS -o /dev/null -w '%{http_code}\n' https://api.tidywipe.online/api/v1/plans (expect 200). Data collected while offline is sent later. |
| TLS or certificate errors | Check the server's clock (timedatectl). A TLS-inspecting proxy needs its CA certificate set as api.ca_file in the configuration. |
sudo tidywipe agent status shows REVOKED | The server was disconnected. To reconnect: sudo tidywipe disconnect --local-only, then connect with a new token. |
| Scan server is greyed out | The server must be online, with Remote Scan turned on (step 10). The page says what is missing. |
| Scan failed: the helper refused to run (owner or mode) | sudo chown root:tidywipe-agent /etc/tidywipe-agent/config.yaml && sudo chmod 640 /etc/tidywipe-agent/config.yaml, then scan again. |
install.sh: checksum mismatch | The download is damaged or modified. Delete it, download again and verify the checksum. |
16.Security and privacy
- The monitoring service runs as the unprivileged user
tidywipe-agent, with no extra privileges and a read-only view of the system apart from its own folder. - It only makes outbound HTTPS connections. No port is opened, and the dashboard cannot run commands on your server.
- What is sent: host name, OS and kernel, agent version, resource metrics (CPU, memory, disks, network counters, uptime), failed services and scan summaries. Scan results include file paths; set
reporting.include_paths: falseto leave them out. - What is never read or sent: file contents, log contents, environment variables, passwords, SSH keys or shell history.
- Each server has its own credential, stored with mode 0600 and never printed. Disconnecting a server revokes it immediately.
- Remote deletion is disabled on the TidyWipe service, and scan-only servers refuse deletion in the agent and the helper as well. Automatic cleanup is off unless you set
cleanup.automatic: trueand install its timer yourself. - Never post enrollment tokens, the credential file or your configuration publicly.
More help: TidyWipe documentation · contact support.