Root v0.4.1

Deterministic dev tools without learning Nix.

Root is a curated package manager for developer CLI tools, backed by Nix. You declare intent in a Rootfile, Root pins exact store paths in root.lock, snapshots before every mutation, and installs to an isolated profile at ~/.root/profiles/default. Every install is verified and undoable.

Built for developers, coding agents, and reproducible dev machines.

Docs · Changelog · Smoke tests

What is Root?

One Rootfile per machine, undo anything.

root catalog              # browse 42 curated tools
root plan install ripgrep # preview, no changes
root install ripgrep      # install via Nix + lock + snapshot
root verify ripgrep       # check ~/.root/profiles/default/bin
root rollback --last      # undo it

Rootfile is intent, root.lock is truth (schema v2 packages, v3 models), snapshots are undo, the Nix profile is isolation. root status, root history, and root doctor tell you what drifted, what happened, and what's broken.

Why Root?

• Undo anything. Every mutation snapshots first; rollback --last restores locked state.
• Verified installs. Binaries are checked in the Root profile, never global PATH.
• Deterministic by default. Curated Nix attributes + pinned store paths in root.lock.
• No Nix to learn. Plan / install / verify / rollback — Root speaks Nix for you.
• Auditable. Append-only event ledger + --json on every command.

How It Works

1. Declare — packages in ~/.root/Rootfile (ripgrep = "latest").
2. Pin — Root resolves Nix attributes to store paths in ~/.root/root.lock.
3. Apply — install into isolated ~/.root/profiles/default, snapshot first, verify after.
4. Undo — root rollback --last restores last locked state; root status shows drift.

Install

Root requires Nix (installer offers Determinate Nix if missing):

curl -fsSL https://raw.githubusercontent.com/sgr0691/Root/main/scripts/install.sh | sh
root doctor

Commands

Cheat-sheet — every command supports --json:

root catalog / search rg / plan install <pkg>  # discover + preview
root install <pkg> / remove <pkg> / update [pkg] # mutate (snapshot first)
root list / status / history / verify <pkg>     # inspect
root sync / restore --lock ./root.lock / rollback --last # reconcile + undo
root run <task> / sandbox create|run|list|destroy # execute + isolate
root models pull / plan models                   # Ollama pull-and-verify (v3 record)
root agent-bundle inspect|export|plan|apply|verify|rollback # explicit config transfer

root import brew is experimental and not part of the v0.4.1 public surface — may change or break without notice.

Exit codes & verify details

0 success, 1 failure, 2 bad args, 3 not found, 4 verify failed, 5 drift, 6 rollback failed, 7 Nix missing, 8 platform missing. verify checks ~/.root/profiles/default/bin, never PATH.

Agent Bundles

root agent-bundle explicitly transfers Codex / OpenCode / Claude working config between machines (manifest.json + blobs/). Same-agent only, no credentials, MCP imported disabled (Codex/OpenCode enable separately; Claude MCP is held in v0.4.1). See Docs/Release/V0_4_AGENT_BUNDLE_SMOKE_TEST.md and Docs/Release/V0_4_1_CLAUDE_SMOKE_TEST.md.

Models

Declared Ollama models ([models."qwen3:8b"] runtime = "ollama") are pull-and-verify, not a bit-pin: plan models previews, models pull fetches by tag and writes a v3 verification record. Restore/rollback copy the record; they never pull or delete weights.

How Root Compares

	Root	brew	curl | sh	raw Nix
Deterministic lock (root.lock)	yes	no	no	manual
Undo (rollback --last)	yes	no	no	manual
Post-install verify	yes	no	no	no
No Nix to learn	yes	yes	yes	no

What v0.4.1 Changed

Patch on the Portable Agent-Bundle release. Full history in CHANGELOG.md.

• Claude adapter — --agent claude on inspect/export/plan/apply/verify/rollback/purge, gated to 2.1.260 exactly.
• Held-subset transfer — allowlist CLAUDE.md + settings.json model only; native ~/.claude/skills then shared skills; executables need --include-executable + --approve.
• Claude MCP is held — no disable-until-enable; --include-mcp / enable return unsupported in v0.4.1 on Claude Code 2.1.260; MCP is held.
• Never touches .claude.json — apply/rollback snapshot settings.json only; stop Claude first.
• Codex 0.150.1 / OpenCode 1.18.27 unchanged, including MCP disable-until-enable.

Limitations (v0.4.1)

• Curated catalog only — 42 tools across 11 categories; arbitrary installs rejected. Run root catalog. docker-client is CLI only.
• Undo covers Root only — rollback restores Root lock/profile state, not Homebrew/manual changes; restore recovery is best-effort.
• Agents + models are honest, not magic — status inspects (never installs agents / pulls models); bundles are same-agent, credential-free; models are tag-pull verification records, digest drift needs re-pull.
• Strict gates — Codex 0.150.1, OpenCode 1.18.27, Claude 2.1.260 exactly; local Ollama 127.0.0.1:11434 only; no digest pull, no endpoint field.
• Online, serial, macOS-first — network required, one mutation at a time (root.lockfile + model-pull.json), macOS tested / Linux best-effort / no Windows; Docker daemon needed for sandbox.
• Nix required — Root manages its own profile but doesn't bundle Nix; if a crash leaves ~/.root/root.lockfile, run root doctor then remove it.

Docs

• Docs/ — restore, sandbox, Nix audits, platform notes
• Docs/Release/ — per-release smoke tests
• CHANGELOG.md — full version history (replaces old "What vX.Y.Z Changed" sections)
• skills/ — agent packs (Codex / Claude / Cursor / generic)

Development

cargo build
cargo test --all
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

License

Apache 2.0 — see LICENSE.