Node Overview

The node agent is a lightweight Rust binary that runs on each machine you want to back up. It connects to the hub over WebSocket, receives commands, and executes restic operations.

Lifecycle

1. Enrollment — The node registers with the hub using a one-time token
2. Connection — The agent connects via WebSocket and maintains a persistent connection
3. Command execution — The hub sends commands (backup, restore, prune, check, stats)
4. Reporting — Results and progress are sent back over WebSocket and REST API

Auto-Managed Restic

The node agent automatically downloads and manages its own restic binary. On first run (or when a new version is available), it downloads the appropriate restic binary for the platform.

System Stats

The node collects and reports system statistics to the hub:

• CPU usage percentage
• Memory usage and total
• Disk usage for monitored paths

Stats are displayed as sparkline charts on the node detail page in the dashboard.

Commands

valvet-node enroll    # Register with a hub
valvet-node run       # Start the agent (foreground)
valvet-node update    # Self-update to latest version from the hub
valvet-node uninstall # Remove the agent and its configuration

Enroll

valvet-node enroll \
  --hub http://hub:4865 \
  --token <enrollment-token> \
  --name "my-server"

Enrollment creates a configuration file and registers the node with the hub. The --name flag is optional — if omitted, the system hostname is used.

Run

valvet-node run

Starts the agent in the foreground. For production use, run as a systemd service (the install script sets this up automatically).