Skip to content
Rivet

Roadmap

Status: Living document · Last updated 2026-07-26 · Current release: v1.0.1

v1.0 shipped on 2026-07-26. The milestones below are kept as the record of how it was reached; Post-1.0 is the part that is still ahead, and feature status is the accurate account of what works today.

v1.0 definition

Section titled “v1.0 definition”

v1.0 lets a developer back up, snapshot, and restore their entire dev environment — across any Linux distribution and macOS, any desktop/window/ tiling manager, and any package manager — to any storage backend (local, NAS, or cloud), with secrets encrypted properly, arbitrary files trackable, and selective restore.

v1.0 is Linux- and macOS-complete; Windows follows in the 1.x line.

macOS moved forward from the post-1.0 1.1–1.3 track into v0.9 (ADR-0007). The reason is ordering, not enthusiasm: macOS needs an os_family field on MachineMetadata, and the on-disk format freezes at v1.0. Adding it before the freeze is one additive field; adding it after means either breaking a published compatibility guarantee in a 1.x minor, or shipping v1.0 with a closed enum that makes every released binary fail to read a snapshot from any future Rivet that learns a new platform.

The staging still holds: the trait seams built for v1.0 (platform, package manager, backend, plugin, crypto) are exactly the seams macOS plugged into, and macOS needed no redesign of any of them — which is the evidence that “the abstractions are proven.”

The five pillars of v1.0, mapped to milestones:

Pillar Milestone(s) ADR
OS-agnostic across distros/WMs/package managers v0.2, v0.3 0001, 0005
Back up to local / NAS / cloud v0.4 0002
Encrypted secrets, done properly v0.5 0003
Track any file; Terraform/Ansible-for-your-env v0.6 0004
Selective restore + polished UX v0.7 ✅ —

Guiding constraints (do not regress)

Section titled “Guiding constraints (do not regress)”

Every milestone inherits these from the Charter and the current code:

  1. Understand, don’t blind-copy. No feature may introduce a whole-$HOME sweep. New capture scope is always named, reviewable, and opt-in.
  2. Safe by default. Dry-run first; destructive actions need explicit confirmation; secrets never leak in plaintext; every overwrite is reversible.
  3. Delegate to native tools. Keep using system git, package managers, and (new) age, rclone, restic rather than reimplementing them.
  4. CI bar holds. fmt, clippy -D warnings, locked tests, release build — plus a growing integration matrix — must stay green on every commit.
  5. Docs and ADRs track code. An architectural change is not done until its ADR and the affected docs are updated in the same PR.
  6. Restore is always free. Reading and restoring a snapshot stays free, complete, and permissively licensed, on every platform and every backend (ADR-0008). Rivet is developed open core, but the entire single-machine tool — all of v1.0 and the post-1.0 platform line — lives in this repository under MIT OR Apache-2.0. No milestone below is narrowed for commercial reasons.

Milestones

Section titled “Milestones”

v0.2 — The abstraction refactor (foundation) — ✅ shipped (v0.2.0)

Section titled “v0.2 — The abstraction refactor (foundation) — ✅ shipped (v0.2.0)”

Goal: no new user-facing features; make the codebase pluggable so every later milestone is additive rather than invasive. This is the single most important milestone — everything else depends on it.

  • Introduce the workspace split from CODE_REVIEW.md (rivet-core, rivet-platform, rivet-backend, rivet-plugins, rivet-cli; add rivet-crypto empty stub). Move existing modules behind the seams intact.
  • Define core traits in rivet-core (see ADR-0001, ADR-0002, ADR-0004):
    • Platform — host/distro/WM detection, package-manager discovery.
    • PackageManager — discover() / plan_install() / install().
    • Backend — init / write_snapshot / read_snapshot / list / history.
    • Plugin — discover / collect / plan_restore / validate.
  • Re-express the Arch code as ArchPlatform + PacmanManager + AurManager behind those traits. git becomes GitBackend. Built-in config groups become Plugin implementors (behaviour identical to today).
  • Fix H1 (file modes) and H2 (symlinks) as part of the Plugin::collect rewrite — the new contract captures mode + FileKind correctly.
  • Fix H3 (restore --revision) now that manifest reads go through Backend.
  • Add H4 (round-trip integration test): snapshot → restore against a temp $HOME, asserting content, mode, and symlink fidelity.
  • Bump snapshot format_version only if the on-disk shape changes; provide a read shim for v1 manifests.

Exit criteria: identical external behaviour to v0.1.1 on Arch, all tests green, new traits documented. Tag v0.2.0.

v0.3 — Multi-distro Linux

Section titled “v0.3 — Multi-distro Linux”

Goal: the same snapshot workflow works on the major Linux families.

  • Add PackageManager impls: apt (Debian/Ubuntu), dnf (Fedora/RHEL), zypper (openSUSE), nix (profile + optional flake), xbps (Void), pacman (already), plus flatpak/snap as cross-distro sources (already).
  • Add Platform detection for distro family + version and multiple desktops/WMs/compositors as Plugins: GNOME (dconf dump/load), Hyprland, Sway, i3, niri, Xfce, Cinnamon, in addition to KDE.
  • Implement ADR-0005 cross-distro package identity: logical-package mapping with an explicit, conservative default (restore within the same distro family; cross-family restores emit per-package “unmapped” warnings and never guess silently).
  • Expand MachineMetadata (L6) so restore can warn about family/WM mismatch.
  • Enrich secret detection toward a gitleaks-style ruleset (L5) ahead of v0.5.

Exit criteria: green snapshot→restore integration tests in containers for Arch, Debian/Ubuntu, and Fedora in CI. Tag v0.3.0.

v0.4 — Storage backends: local, NAS, cloud

Section titled “v0.4 — Storage backends: local, NAS, cloud”

Goal: put snapshots anywhere, not just a Git remote.

  • Implement ADR-0002 Backends beyond Git:
    • FsBackend — a plain local/mounted directory (covers NAS via an already mounted SMB/NFS path).
    • RcloneBackend — the broad cloud/NAS answer (S3, B2, Drive, Dropbox, SFTP, WebDAV, SMB) by delegating to rclone.
    • ResticBackend — deduplicated, encrypted, incremental snapshots for users who want history without Git.
    • Keep GitBackend as the reviewable default.
  • Snapshot-level encryption at rest for non-Git backends (restic native; age-wrap for fs/rclone). This is distinct from the secrets vault (v0.5): here the whole snapshot can be encrypted before it leaves the machine.
  • rivet init --backend <git|fs|rclone|restic> and a backend block in rivet.toml. Multiple destinations allowed (fan-out push).

Exit criteria: same snapshot restored from each backend type in integration tests. Tag v0.4.0.

v0.5 — Encrypted secrets vault

Section titled “v0.5 — Encrypted secrets vault”

Goal: stop merely excluding secrets — include them, encrypted properly.

  • Implement ADR-0003. Recommended design (rationale in the ADR):
    • age (via the age Rust crate) as the built-in encryption primitive: modern, small, audited, no GPG-keyring pain.
    • Per-user identity key stored outside any snapshot (default ~/.config/rivet/identity.age, never committed); support age recipients so a snapshot can be decryptable on multiple machines / by a backup key.
    • Optional plugin encryptors for users already invested elsewhere: pass, Mozilla SOPS, and Bitwarden/rbw. Rivet stays the orchestrator.
    • rivet vault add/list/rm, rivet vault seal/unseal; secret files live in secrets/*.age in the snapshot, plaintext only ever on the local machine.
    • The existing secret scanner stays on as a safety net: it now blocks plaintext secrets from the non-encrypted paths, while the vault is the sanctioned channel for the ones you do want to keep.

Exit criteria: a secret survives snapshot→push→pull→restore encrypted the whole way, with keys never present in any backend. Security review of the crypto path. Tag v0.5.0.

v0.6 — Arbitrary file tracking + user plugins (“Terraform for your env”)

Section titled “v0.6 — Arbitrary file tracking + user plugins (“Terraform for your env”)”

Goal: track anything, declaratively, without editing Rust.

  • Implement ADR-0004 user-facing side:
    • rivet track <path> / rivet untrack <path> and a [[track]] table in rivet.toml for arbitrary files/dirs with per-entry include/exclude globs, secret handling (plaintext-blocked | vault), and mode/symlink policy.
    • Declarative plugins (TOML/manifest, no compilation): a plugin file describes discovery paths, package dependencies, and optional export/import hooks (e.g. code --list-extensions, dconf dump). Ships the built-ins as data; lets users drop in their own.
    • Plugin validation + sandboxing posture: hooks are explicit, reviewed commands; document the trust model.
  • This is the milestone that makes Rivet feel like “Terraform/Ansible for your dotfiles + stack”: one declarative file, reproducible environment.

Exit criteria: a user adds a new app with a TOML plugin + tracks a custom dir, round-trips it. Tag v0.6.0. ✅ Shipped — both round-trips are covered by tests, and docs/TRACKING.md documents the format and the hook trust model.

Shipped with one deliberate narrowing: the built-ins remain compiled-in data (StaticPlugin) rather than being re-expressed as shipped TOML files. They already implement the same Plugin trait the declarative loader produces, so there is one code path either way; converting them would move reviewed, test-covered data into files without changing behaviour, and is better done alongside v0.8’s packaging work if at all.

v0.7 — Selective restore & UX

Section titled “v0.7 — Selective restore & UX”

Goal: precise control and a pleasant interface.

  • Per-item selective restore is partly present; extend to config groups and individual files, with a clear restore preview/diff.
  • TUI (ratatui) for checklist approval, snapshot history browsing, diff review, and restore planning — CLI remains the automation API.
  • rivet audit (L7) as the drift/compare verb; machine-readable --json everywhere (L8).
  • Profiles: named machine profiles (laptop vs workstation) selecting subsets.

Exit criteria: full migration doable from the TUI. Tag v0.7.0. ✅ Shipped — with the exit criterion met on the restore side, honestly stated: the TUI browses history, reviews per-file diffs, edits the restore selection and applies it, so arriving at a new machine and rebuilding it is a TUI-only flow. Capturing still requires rivet snapshot (and vault/track changes their own verbs) — write operations that deserve an explicit command in shell history rather than a keystroke. Documented in docs/TUI.md, docs/PROFILES.md and docs/JSON.md.

v0.8 — Hardening, scale, and docs

Section titled “v0.8 — Hardening, scale, and docs”
  • CI integration matrix: container jobs per distro family running the full snapshot→restore round trip, plus each backend and the vault path.
  • Performance pass for large environments (parallel collect, streaming hashing, skip-unchanged). Benchmark against a realistic dotfile+package set.
  • Documentation site (mdBook) — superseded and shipped early. Built as Astro + Starlight in web/ instead of mdBook, because the milestone needed a landing page as well as docs and Starlight gives both plus Pagefind search. docs/ stays the source of truth and the site syncs from it at build time (docs/WEBSITE.md). Remaining for v0.8: the concept pages, a migration guide, and a written threat model, all held to docs/DOCUMENTATION.md.
  • FOSS hygiene (L1–L2): LICENSE-MIT, LICENSE-APACHE, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, issue/PR templates.

Exit criteria: green matrix, published docs. Tag v0.8.0.

v0.9 — macOS support, then release candidate

Section titled “v0.9 — macOS support, then release candidate”

Rescoped 2026-07-25 (ADR-0007): macOS lands here rather than post-1.0, because it needs an additive MachineMetadata field and the format freezes at v1.0. The freeze then applies to everything below it.

  • ✅ macOS on Apple Silicon and Intel, both native. OsFamily split from DistroFamily (both tolerant of unknown variants), MacOsPlatform with Rosetta-aware architecture detection, HomebrewManager/MasManager/ MacPortsManager, a brew column in the package map, nine macOS plugin groups, per-domain defaults hooks, and the macOS-specific safety guards (~/Library deny list, TCC diagnostics, case-collision refusal).
  • ✅ macOS CI on macos-14 (Apple Silicon native; Intel cross-compiled after GitHub retired the macos-13 runner); a universal release binary fused with lipo; a Homebrew tap as the primary macOS install channel.
  • Feature freeze after macOS. Real cross-distro migration dry-runs on clean VMs (Arch → Fedora → Ubuntu) covering packages, WM config, tracked files, and vault, plus the macOS cases in v0.9-macos-spec.md.
  • External security review of crypto + restore paths.
  • ✅ Stabilise the on-disk snapshot format and the plugin manifest schema; document a compatibility policy — COMPATIBILITY.md. SNAPSHOT_FORMAT_VERSION stays at 2: it is frozen, not bumped.
  • ✅ Prebuilt release binaries (musl static) via CI, signed with Sigstore and reproducible.
  • ✅ crates.io publish rehearsed end-to-end. The crates publish as rivetsnap-*, because rivet, rivet-core, and rivet-cli are held on crates.io by unrelated projects; the installed binary is still rivet.

Exit criteria: RC survives real migrations with no data-loss surprises. Tag v0.9.0ᵣᶜ, then v1.0.0.

v1.0.0 — Linux- and macOS-complete

Section titled “v1.0.0 — Linux- and macOS-complete”

All five pillars stable on the major Linux families and on macOS, documented, tested in CI, and validated on real migrations. First GitHub Release — releases are reserved for milestones, and this is the milestone.

Post-1.0

Section titled “Post-1.0”
  • v1.1+ — Windows: WingetManager/ScoopManager, registry-aware plugins, path-model adjustments. Highest-risk platform; scoped last on purpose. The OsFamily axis added in v0.9 is what makes it additive rather than a format break.
  • macOS depth: broader application coverage in the built-in plugin set, and optional notarization of the release archive so a direct download needs no xattr step.
  • Ecosystem: a plugin registry/index, signed plugins, and a stable external plugin ABI if declarative TOML proves insufficient.

How this roadmap gets executed

Section titled “How this roadmap gets executed”
  • One focused commit per logical change, pushed once its tests pass. Architecture is settled in an ADR before implementation, not during it — see docs/adr/.
  • Tag at each milestone (v0.2.0 … v1.0.0). A GitHub Release is cut only at v1.0.0 and at any public preview or release candidate; tags are cheap, releases are a statement.

Roadmap at a glance

Section titled “Roadmap at a glance”
Milestone Theme Headline outcome
v0.2 Abstraction refactor ✅ Pluggable traits; modes/symlinks/--revision fixed
v0.3 Multi-distro apt/dnf/zypper/nix + more WMs; cross-distro package mapping
v0.4 Backends Local, NAS, cloud (fs/rclone/restic) + encryption at rest
v0.5 Secrets ✅ age vault; optional SOPS (pass/Bitwarden deferred)
v0.6 Track anything ✅ rivet track + declarative user plugins
v0.7 UX Selective restore, TUI, audit, profiles
v0.8 Hardening CI distro matrix, perf, FOSS files (docs site shipped early)
v0.9 macOS + RC macOS on both architectures, real migrations, security review, binaries
v1.0 Stable ✅ Linux- and macOS-complete; CLI frozen under semver; signed, provenanced releases
v1.0 Linux- and macOS-complete All five pillars stable + documented
1.1+ Windows Same traits, new platform