Incus Backup UI

Dark-mode control plane for Incus VM backups using ZFS block devices, Restic, and S3-compatible storage.

Layout

• backend/: Express API that validates Incus VMs, runs host commands with spawn, manages in-memory jobs, and enforces one active backup/restore per VM.
• frontend/: React/Vite dashboard for health, VM status, snapshots, backup jobs, and explicit destructive restore confirmation.
• incus-backup-ui-plan.md: Product and implementation plan.

Backend

cd backend
cp .env.example .env
npm install
npm run dev

The backend must run on the Incus host with permission to access Incus, ZFS, /dev/zvol, Restic, and S3 credentials. In production this usually means running it as root or through a tightly scoped service account with the needed privileges.

Required commands:

• incus
• zfs
• restic
• udevadm
• dd

Frontend

cd frontend
npm install
npm run dev

Set VITE_API_URL if the API is not available at http://localhost:3000/api.

If API_TOKEN is set in the backend, set matching VITE_API_TOKEN for the frontend.

Settings Page

The UI includes a Settings page for editing the backend environment values directly. It writes to backend/.env through GET /api/settings and PUT /api/settings.

If API_TOKEN is set from the Settings page, the browser stores that token locally and immediately uses it for subsequent API requests. If a token is already configured on the backend and the browser does not know it yet, start the frontend with VITE_API_TOKEN or clear/update the token manually in browser storage.

Changing most values applies to new API calls and jobs immediately. Changing PORT requires restarting the backend process.

Safety Notes

Restore is intentionally guarded twice: the backend validates the snapshot against the VM, and the UI requires typing the VM name before sending the restore request. Restore jobs are never retried automatically.