One backup platform for your entire homelab.
BackupOS is a self-hosted backup management platform built on Restic. Back up Proxmox VMs and LXCs, Linux hosts, Windows machines, Docker / Compose stacks, databases, and NAS shares — from one dashboard, to one or more repositories, with YAML-defined restore specs that actually work when you need them.
Status: V1 launch candidate. Active development. See release notes for the current changelog.
- Unified dashboard — every repository, job, agent, and restore spec in one place
- Restic-native — content-addressed storage, deduplication, incremental-forever, fully readable by the
resticCLI on its own - Eight repository backends — local filesystem, NFS, SMB / CIFS, SFTP, Amazon S3 (and S3-compatible), Cloudflare R2, Backblaze B2, Rclone
- Nine source types — filesystem, Compose project, Docker volume, database (PostgreSQL / MySQL / MariaDB / SQLite / Redis), Proxmox VM, Proxmox LXC, XCP-ng VM, Windows VSS, NAS share
- Cross-platform agents — Linux (Node bundle, systemd) and Windows (native binary, Windows Service)
- Hypervisor integration — Proxmox VMs and LXCs via the Proxmox API; XCP-ng VMs via XAPI with Changed Block Tracking (CBT)
- PBS protocol target — point Proxmox VE at BackupOS as a Proxmox Backup Server-compatible target, no agent install on the Proxmox host required
- YAML restore specs — define, version, and rehearse your recovery procedure as code, with a guided form for VM restores
- DR Mode — guided checklist that walks you through restore specs during an incident
- Verification — scheduled restore tests that prove backups are actually usable, not just present
- Nine alert channels — email, Slack, Discord, Telegram, Pushover, Gotify, ntfy, generic webhook, Twilio SMS
- Cost forecasting — per-repository storage growth tracking with projected monthly spend
- Tamper-evident audit log — SHA-256 hash chain across every privileged action, with forensic mode
- OIDC SSO — Authentik, Okta, Duo, plus local password + TOTP fallback
- Encryption at rest — every stored credential (alert channel secrets, repository passwords, OIDC client secrets, SMTP passwords) encrypted with a per-instance key
The recommended deployment is the native installer — it sets up both the web app and the PBS protocol service as systemd units. A Docker image is also provided for hosts where systemd isn't an option, but it ships only the web app (no PBS protocol service).
Requirements: Linux host, root or sudo, Node.js 20+, pnpm 9+, Go 1.22+, restic 0.16+, openssl, rsync.
git clone https://github.com/dariusvorster/backupos.git ~/backupos
cd ~/backupos
sudo bash scripts/server-install.shThe installer creates the backupos system user, builds the web app and the Go-based PBS protocol service, generates /etc/backupos/server.env with random secrets, and installs systemd units for backupos (web, port 3093) and backupos-pbs (PBS protocol, port 8007).
Open http://<host>:3093 and create your admin account — the first signup is automatically the admin. After that, additional users join via invite from Settings → Users.
Full guide: docs/getting-started/install-self-hosted.
cp .env.example .env
# Edit .env — set ENCRYPTION_KEY, BETTER_AUTH_SECRET, BETTER_AUTH_URL
docker compose up -dOpen http://localhost:3000.
Use this if you don't need to back up Proxmox via the PBS protocol target. For agent-driven and hypervisor-API backups it's identical to the native install.
In the BackupOS UI: Agents → Enroll agent. Name the agent (typically the hostname), click Generate token & enroll, and copy the install command shown on the next page.
Run it on the host you want to back up:
curl -fsSL https://your-backupos-host:3093/install.sh \
| sudo BACKUPOS_TOKEN=<token-from-ui> bashThe installer drops the agent at /opt/backupos-agent/, registers a backupos-agent.service systemd unit, and connects out to the BackupOS server over WebSocket. No inbound firewall rules are required on the agent host.
For Windows, the agent detail page also shows a PowerShell snippet (iwr ... | iex) that installs backupos-agent.exe as a Windows Service.
Full guide: docs/getting-started/enroll-agent.
Repositories → Add repository in the UI. Pick a backend, fill in the credentials, click Test connection (or Test mount for NFS / SMB). Save, then click into the new repository and Initialize repository with a strong password.
Strongly recommended: enable escrow on the repository detail page after initialization. It encrypts the repository password with a master passphrase you set; if you ever lose the password, you can recover it from Settings. Without escrow, a forgotten repository password means every snapshot in that repository is permanently unreadable.
Full guide: docs/getting-started/connect-repository.
cd ~/backupos
git pull origin main
sudo bash /opt/backupos/scripts/server-install.sh update --source ~/backuposThe installer self-updates, stops the services, rebuilds, and restarts. Existing data, secrets, and config are preserved.
docker compose pull
docker compose up -dDatabase migrations run automatically on startup.
Re-run the original install command on the agent host. The install script is idempotent — it upgrades in place and preserves the existing token. Or, on Linux:
sudo bash /opt/backupos-agent/install.sh update- Web app — Next.js + tRPC, runs as
backupos.service. Stores everything in a single SQLite file at/var/lib/backupos/backupos.db. - PBS protocol service — Go binary, runs as
backupos-pbs.serviceon port 8007. Speaks the Proxmox Backup Server wire protocol so PVE can write backups directly to BackupOS without an agent on the Proxmox host. Shares the SQLite database with the web app. - Agents — Linux: Node.js bundle (
agent.js) at/opt/backupos-agent/. Windows: native binary (backupos-agent.exe) under Program Files. Both speak the same WebSocket protocol. - Repositories — standard Restic-compatible storage. BackupOS does not introduce a proprietary format.
Full architecture: docs/introduction/architecture-overview.
git clone https://github.com/dariusvorster/backupos
cd backupos
pnpm install
pnpm --filter @backupos/db build
pnpm --filter @backupos/engine build
pnpm --filter @backupos/agent build
pnpm --filter @backupos/web exec next buildThe Go-based PBS protocol service is built separately:
cd services/backupos-pbs
go build -o ../../bin/backupos-pbs ./cmd/backupos-pbsThe native installer wraps both build paths in scripts/server-install.sh.
BackupOS is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). The full license text is in the LICENSE file at the repo root.
A commercial license is available for organizations that prefer not to comply with the terms of the AGPL-3.0 (e.g. proprietary forks, white-label deployments, SaaS relicensing). Contact licensing@homelabos.app for details.
The Pro tier (paid features such as unlimited agents, RBAC, SSO, and integration tokens) is a separate commercial product gated by a JWT license key — see docs/design/licensing.md. The Pro tier is independent of the source-code license: AGPL-3.0 source + Pro tier features is the supported self-hosted commercial offering.
V1 launch candidate. Active development tracked on the issue tracker.
Known scope deferred to V1.x:
- MongoDB apphook backup + restore (tracked in #378)
- DR Mode browse-and-restore for individual files within a snapshot (tracked in #381)
- Cloud sync tier (currently no managed cloud product — BackupOS is self-hosted only)
- Licensing / paid tier infrastructure (tracked in #336)
- macOS agent
Issues and feedback welcome at github.com/dariusvorster/backupos/issues.