State A · form
restic-manager
v0.1.0-alpha
steve@dcglab
Dashboard/Add host

# Add a host

Mints a one-time enrolment token (TTL 1 hour) and binds the repo credentials to it. The token can only be used once — generate a fresh one if it expires or you typed something wrong.

### Host

Hostname
Becomes the host’s display name. Most operators use the box’s actual hostname so logs line up.
Tags
prod × cache ×
Free-form. Used for filtering and grouping on the dashboard.

### Restic repository

Repo URL
repo:
Whatever restic -r would accept. Most fleets terminate at a restic/rest-server; s3: and b2: URLs work equally well.
Repo username · optional
For rest-server with htpasswd, this is the per-host user.
Repo password
Encrypted at rest using the server’s AEAD key. Pushed to the agent only over the authenticated WebSocket.
What happens next

1. 1
   You get a one-time install command
   A curl … | sh snippet with the server URL and a 1h token baked in.
2. 2
   You run it on the box you want to back up
   Installer creates a service user, drops the agent binary, registers a sandboxed systemd unit, and enrols.
3. 3
   The host appears on the dashboard within seconds
   Server pushes the encrypted repo creds over the WS on first hello; agent decrypts and persists to secrets.enc.
4. 4
   You hit “Run backup now”
   First snapshot lands in the repo. Subsequent ones run on whatever schedule you set (Phase 2).

Prerequisite

restic ≥ 0.16 must already be installed on the target host. The agent does not install it for you — different distros, different package managers, too much surface area to maintain.

State B · token minted, install command shown
restic-manager
v0.1.0-alpha
steve@dcglab
Dashboard/Add host/prod-redis-01

# Token minted

expires in 59m 54s

Run the snippet below on the target box. The host will appear on the dashboard within a few seconds of the agent connecting.

Install command · paste-and-run

    curl -fsSL https://restic.lab.example/install.sh | sudo \
      RM_SERVER=https://restic.lab.example \
      RM_TOKEN=HdqFbQh8U-I1fb52iP1M8qxvoYS5t9VZ-T-yghr_CzA sh

Awaiting agent connection
prod-redis-01 — enrolment will mark this online
11:42:18.221 server token minted · 1h ttl
awaiting POST /api/agents/enroll …
If the agent doesn’t appear

- Check the box can reach https://restic.lab.example over HTTPS.
- Check restic --version ≥ 0.16 — the installer won’t bail on this, but backups will fail.
- Check journalctl -u restic-manager-agent -n 50 on the target box.
- Token expired? Mint a new one — they’re cheap.