Install on Linux and macOS

You install the Restow agent with one command that Restow creates for you. The command carries a one-time token, so you never type credentials on the machine.

Requirements

On the machine

Linux: systemd, x86_64 or aarch64, root rights (sudo), curl, and sha256sum or shasum.
macOS: macOS 13 (Ventura) or newer, Intel or Apple Silicon, an administrator account (sudo) and curl.
HTTPS to Restow. The machine must reach your Restow instance over HTTPS. The agent only connects out. No inbound port is needed or opened.
A correct clock. Certificate checks fail on a machine whose clock is far off.
A trusted certificate. The agent uses the operating system’s trust store. If your instance uses a certificate from a private certificate authority, the CA must be in that trust store, or, on Linux, in a file named by SSL_CERT_FILE (see Proxy and private CA). The agent has no setting of its own for this.

In Restow

Set the public URL of your installation in the settings. The address in the install command comes from it. If none is set, Restow uses the address of your browser and warns you, and the machine must be able to reach exactly that address.
Use an https:// address. The install scripts refuse a plain http:// instance. The interface warns you about an unencrypted address before you connect a machine, because the token and the secrets of the agent would travel unencrypted.

Create the install command

In the sidebar section Server/endpoint backup, open Servers or Clients (or Agents, which lists both).
Choose New server or New client.
Choose the operating system: Linux or macOS. Windows is shown as “Planned” and cannot be chosen.
Optionally give the machine a name. It is shown in the lists instead of the host name, and you can change it later.
Choose Create install command and copy the command.

The window shows when the machine has connected. You can close it and find the machine in the list later.

The command is shown only once, because it contains the token. If you lose it, create a new one. Commands that nobody has used yet are listed under Pending enrollments, where you can revoke them.

Run the command

Run it on the machine you want to back up.

# Linux
curl -fsSL https://<your instance>/install/linux.sh | sudo RESTOW_TOKEN='<token>' sh
# macOS
curl -fsSL https://<your instance>/install/macos.sh | sudo RESTOW_TOKEN='<token>' sh

Restow fills in your instance address and the token when it shows you the command.

What the script does

The script is served by your own instance, with its address and the agent version filled in.

It detects the CPU architecture and downloads restow-agent, restic and SHA256SUMS from <instance>/install/agent/<version>/<os>-<arch>/. The files come from your instance, not from the internet.
It verifies both binaries against SHA256SUMS. If a checksum does not match, nothing is installed.
It installs /usr/local/bin/restow-agent and /usr/local/lib/restow-agent/restic.
It installs and enables the service: the systemd unit restow-agent.service on Linux, the LaunchDaemon com.restowbackup.agent on macOS.
It runs restow-agent enroll. This exchanges the token for credentials and checks that the instance and the backup repository accept them.
It starts the service and prints the status.

The token

It is valid for 24 hours and can be used once.
Restow stores only a SHA-256 hash of it.
The script reads it from the environment only. It is never printed and never written to disk.
sudo RESTOW_TOKEN=... sh puts the token in the process list of the machine while the command runs. Other users on that machine could see it during that time. It expires after use, and after 24 hours at the latest.
If enrollment fails on the server side (for example because the storage target is not reachable), the server undoes everything and frees the token. You can run the same command again. A request that is invalid (for example an empty host name) does not use the token either.

Safe to run again

You can run the command again at any time. It repairs or upgrades the installation in place, keeps an existing enrollment and never installs twice. On a machine that is already enrolled, the token is not needed.

macOS: grant Full Disk Access

macOS protects Desktop, Documents, Downloads, iCloud Drive and other folders. Without access the agent skips those files, the backup ends as partial and the run log says so.

Open System Settings > Privacy & Security > Full Disk Access.
Add /usr/local/bin/restow-agent.
If protected folders are still reported after that, also add /usr/local/lib/restow-agent/restic.

The next backup then includes those files.

On Macs that are managed through MDM, deploy a Privacy Preferences Policy Control profile instead, which grants the same access without a person clicking through System Settings.

Check the status

On the machine:

restow-agent status

It shows the local state and needs no root rights. --json gives the same for scripts. In Restow, the endpoint appears in the list and its status changes to Online after the first contact.

A fresh server enrollment waits for the next scheduled slot. To start the first backup at once, open the endpoint in Restow and choose Back up now. The machine picks the request up with its next contact, usually within a few minutes.

Command line

restow-agent enroll        Enroll this machine (RESTOW_TOKEN and RESTOW_URL from the environment)
restow-agent run           The service main loop (what systemd / launchd execute)
restow-agent status        Local state, no root needed (--json for scripts)
restow-agent backup-now    Run one backup in the foreground (exit 0 ok, 3 partial, 1 failed)
restow-agent service ...   install | start | stop | restart | status
restow-agent uninstall     Remove the agent (--yes, --keep-logs)
restow-agent version       Version, commit, build date (--short for the number only)

--debug, or RESTOW_DEBUG=1, turns on verbose logging.
enroll --force enrolls the machine again with a new token. The old endpoint stays in Restow until you revoke it. See Uninstall.
enroll --allow-insecure-http exists for local development only. The install scripts refuse it unless RESTOW_ALLOW_INSECURE_HTTP=1 is set, and the agent prints a warning every time.

Files

Path	Content
`/usr/local/bin/restow-agent`, `/usr/local/lib/restow-agent/restic`	The binaries. `restow-agent.prev` is the previous agent after an update.
`/etc/restow-agent/state.json`	Enrollment: instance URL, endpoint id, agent secret, repository URL and password. Mode 0600.
`/var/lib/restow-agent/status.json`	Runtime status for `restow-agent status`. No secrets.
`/var/lib/restow-agent/cache`	The restic cache. It holds metadata of the repository, can grow to a few GB for large repositories, and can be deleted.
`/var/lib/restow-agent/{tmp,restic-tmp,outbox}`	Temporary restore copies, restic option files and run reports that could not be delivered yet.
`/var/log/restow-agent/agent.log`	The agent log, rotated at 5 MB, 3 files kept. On Linux it is also in the journal. On macOS, `launchd.log` holds crash traces.
`/etc/systemd/system/restow-agent.service`	The systemd unit (Linux).
`/Library/LaunchDaemons/com.restowbackup.agent.plist`	The LaunchDaemon (macOS).

Proxy and private CA

The agent passes proxy settings and a private CA bundle on when they are set in the service environment. The variables are HTTPS_PROXY, NO_PROXY and, on Linux, SSL_CERT_FILE. On Linux you set them with a systemd drop-in:

sudo systemctl edit restow-agent

Add, for example:

[Service]
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1"
Environment="SSL_CERT_FILE=/etc/ssl/certs/company-ca.pem"

Then restart the service:

sudo systemctl restart restow-agent

Adding a private CA to the operating system’s trust store is the simpler route when you can. The same variables also reach restic and your hooks, because they are on the short list of variables the agent passes on.

After the install

Profiles, schedule and hooks: choose what is backed up and when.
Troubleshooting: if the script or the first backup does not work.