Restic Integration#

Zerobyte wraps restic as its backup engine. The core backup command is implemented in packages/core/src/restic/commands/backup.ts, which constructs the restic CLI invocation, streams its JSON stdout for live progress, and parses the final summary line on completion. The agent process (apps/agent) is the runtime that actually executes restic; the server delegates backup jobs to it via an agent protocol.

JSON Progress Output#

Restic is invoked with --json output mode via safeSpawn. Each line of stdout is parsed as JSON 1:

• Lines with message_type: "status" are validated against resticBackupProgressSchema and forwarded through the onProgress callback.
• The final line with message_type: "summary" is parsed by resticBackupOutputSchema and returned as the backup result.
• Non-JSON lines and parse errors are silently ignored; stderr lines are logged and collected for warning details.

Progress fields tracked via resticBackupProgressMetricsSchema: seconds_elapsed, seconds_remaining, percent_done, total_files, files_done, total_bytes, bytes_done, current_files.

Summary fields from resticBackupRunSummarySchema: total_duration, snapshot_id, plus file/dir/blob counters and total_bytes_processed.

The agent relays progress events upstream via backup.progress agent messages, which the server stores in cache and emits as SSE events for the UI 2.

Filesystem Boundary Handling (--one-file-system)#

When options.oneFileSystem is true, the flag --one-file-system is appended to the restic command 3. This prevents restic from crossing mount-point boundaries — useful when backing up a volume that may have sub-mounts.

The agent resolves the filesystem type and mount point for a given path using getMountForPath, which reads and parses /proc/self/mountinfo.

/proc/self/mountinfo Parsing#

readMountInfo in apps/agent/src/volume-host/fs.ts reads /proc/self/mountinfo directly. For each line it:

1. Splits on the - separator to extract the left (path info) and right (fs type) fields.
2. Reads left[4] as the raw mount point and right[0] as the filesystem type.
3. Unescapes octal-encoded characters (e.g. \040 → space) via unescapeMount.

getMountForPath then finds the longest-prefix matching mount point for any target path — the standard algorithm for resolving which mount a file lives on.

This data feeds assertMounted in utils.ts, which validates that a volume is mounted at the expected path with the correct filesystem type before a backup starts.

Automatic Exclusion of Zerobyte's Own Paths#

The agent defines DEFAULT_EXCLUDES in apps/agent/src/restic/deps.ts:

These are injected as --exclude flags before any user-defined exclusions 4. Paths are overridable via environment variables RESTIC_PASS_FILE and ZEROBYTE_REPOSITORIES_DIR 5.

Additionally, restore operations are blocked from targeting a broader set of protected paths including /var/lib/zerobyte/repositories, /var/lib/zerobyte/cache, /var/lib/zerobyte/ssh, and /root/.config/rclone 6.

Exit Code Handling#

Restic's exit codes are handled explicitly 7:

User-triggered cancellations (via AbortSignal) return a warningDetails message instead of throwing 8.

Key Files#