restic-manager/docs/book/src/getting-started/enrolling-hosts.md

Enrolling your first host

The control plane only knows about hosts you've explicitly enrolled. Two paths exist:

1. Token-based enrolment — admin generates a token, pastes it into an install command on the host. The host appears immediately, already mapped to the desired repo.
2. Announce-and-approve — the agent runs without a token, "announces" itself to the server, and a human in the UI accepts the announcement.

Token-based is the default and what most operators want; the announce flow exists for the case where you can't easily paste a secret onto the host (auto-imaged endpoints, scripted bring-ups from a config repo).

Token-based enrolment

From the UI

1. Click + Add host on the dashboard.
2. Fill in the hostname, the restic repo URL, and the repo credentials. The credentials are AEAD-encrypted at the server immediately; what you paste is what the agent receives.
3. Optionally pick the initial source paths — these become the first source group on the host.
4. Submit. The server mints a one-time token and shows you a copy- pasteable install snippet.

On the host (Linux)

curl -fsSL https://restic.example.com/install/install.sh | \
    sudo RM_SERVER=https://restic.example.com \
         RM_ENROL_TOKEN=<token> \
         bash

The script:

1. Detects architecture (amd64 or arm64).
2. Downloads the agent binary from /agent/binary?os=…&arch=….
3. Drops the systemd unit at /etc/systemd/system/restic-manager-agent.service.
4. Runs the agent in -enrol mode, which posts the token and stores the persistent bearer it gets back.
5. Enables and starts the unit.

Within seconds the host should appear on the dashboard as online.

On the host (Windows)

$env:RM_SERVER  = "https://restic.example.com"
$env:RM_ENROL_TOKEN = "<token>"
iwr -useb $env:RM_SERVER/install/install.ps1 | iex

Equivalent shape: registers a Windows service via the SCM (see P2-16 for details), runs -enrol, starts the service.

Recovering a lost token

Tokens are single-use and short-lived (1h). If you closed the tab before pasting the install command, head to the Add host page — outstanding tokens are listed there with a Regenerate button. Regenerating revokes the old token's hash and mints a fresh raw token while preserving the original repo credentials and initial paths. (NS-02 in tasks.md if you want the design rationale.)

Announce-and-approve

If the host can reach the server but you don't want to paste a secret on it, run the agent in -announce mode:

restic-manager-agent -announce \
                     -server https://restic.example.com \
                     -hostname myhost

The host appears in the Pending hosts panel on the dashboard with its hostname, OS, arch, and the source IP that announced it. Click Accept, fill in the repo URL + credentials, and the server pushes the bearer over the still-open WebSocket. No back-and-forth round trip.

If you don't accept within an hour the announcement is swept.

What happens on the agent

After enrolment, the agent:

1. Connects via WebSocket to /ws/agent with its bearer token.
2. Sends a hello envelope with its OS, arch, agent version, restic version, and protocol version.
3. Receives a config.update carrying its encrypted repo credentials and any source-group paths.
4. Sits idle, sending a heartbeat every 30s. Operator-driven "Run now" actions arrive as command.run envelopes; scheduled jobs are driven by the agent's local cron.

Auto-init of the repository

The first time a backup runs, the agent invokes restic init against the repo you configured at enrolment. If the repo already exists (config file already exists) the agent treats it as a success and proceeds. The host's repo status (unknown → ready / init_failed) is surfaced under the vitals strip on the host detail page; if init fails, save fresh credentials in the Repo tab to retry.