chad/bubblebox
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 6 Packages Wiki Activity Actions
Page: Home
Pages
Architecture Build and Run Decisions Devshells Entrypoints GC and Generations Gotchas Home Management Plan Home Review 2026 08 21 Status Testing
1 Home
crussell edited this page 2026-09-09 19:32:21 -04:00
Table of Contents

bubblebox wiki

The documentation home for bubblebox — a userspace, no-sudo, relocatable, content-addressed package manager (a nix-lite for tools). Each package is an OCI image built into a composefs descriptor in a shared content-addressed store; entrypoints compose packages at runtime (rootless overlayfs-over-FUSE) into a bwrap sandbox, with a self-contained binary cache (HTTPS pull, S3-compatible push).

For AI agents: AGENTS.md in the repo root is the entry point — it points here. This wiki is the source of truth for architecture, decisions, and gotchas. Pages are plain markdown; fetch them from https://git.crussell.io/chad/bubblebox/wiki/raw/<Page> (no auth needed, repo is public) or clone bubblebox.wiki.git.

Provenance: migrated 2026-09-09 from the repo's AGENTS.md hub-and-spoke docs (the wiki experiment — human- and LLM-friendly docs home).

Start here

  • Architecture — repo layout, the store/mount XDG split, cross-repo relationship (engine ↔ pkgs ↔ cn)
  • Build and Run — iterating on the CLI (no host toolchain), running packages, sources & caches
  • Entrypoints — the TOML schema, override layering, deep_merge vs stack_merge, composed-sandbox semantics
  • Gotchas — hard-won traps (FUSE liveness, overlay order, zsh word-splitting, digest non-reproducibility)

Feature-area designs (spokes)

  • GC and Generations — the declarative profile.toml/profile.lock layer, generation archive, store GC
  • Devshells — composable, stackable dev environments (bubblebox shell, base inheritance, project bubblebox.toml)
  • Home Management Plan — Phase B/C: declarative files/units in profile.toml, reconciled by apply (design record)

Records

  • Decisions — the locked design-decision table
  • Status — what's built vs deferred, per phase
  • Testing — the no-network cache test loop
  • Review 2026-08-21 — the full code+docs review (T-numbered findings; the historical audit)

Related repos

  • bubblebox-pkgs — package source recipes (Containerfiles + entrypoints); its DESIGN-ecosystem.md covers the public ecosystem layer
  • cn — NixOS fleet config; per-host profile.toml + the cjust recipes that drive bubblebox