bubblebox-pkgs

A bubblebox package source — the build recipes (Containerfile) and default runtime specs (entrypoint.toml) for the tools this source ships. Consumed by the bubblebox engine via a source registration (local path or git URL) and declared in a host's profile.toml.

This is the nixpkgs-analog layer: packages and their default entrypoints. User dotfiles are a separate concern (they live in the host config repo and are reached at runtime via writable_home), and the bubblebox engine is a separate repo at ~/Code/bubblebox.

Layout

<pkg>/
  Containerfile       # the OCI image build recipe (the "package")
  entrypoint.toml     # the default runtime/sandbox spec (the "entrypoint")
  ...                 # vendored resources the Containerfile COPYs (scripts, configs)

A package is just an OCI image; an entrypoint is how bubblebox runs it — which /usr/bin/<binary> to exec, an optional compose list (overlay more packages at runtime), and a sandbox spec (binds, env, writable flags). The package author authors both, co-located, because they know what the tool needs to run sanely.

A virtual entrypoint — one that reuses another package's image — ships an entrypoint.toml with no Containerfile (e.g. age-keygen/ sets package = "age" + binary = "age-keygen", exec'ing /usr/bin/age-keygen from the age image with no duplicate build).

Entrypoint schema (default layer; the user override deep-merges over this)

package = "age"                       # required: the OCI image to mount
binary  = "age-keygen"                # optional: defaults to <package>
compose = ["nvim", "rg", "fd"]        # optional: defaults to [package]

[sandbox]                            # all optional
writable_home = true                  # /home rw (default ro)
writable_run  = true                  # /run/user/$UID rw (default ro)
dirs          = ["/dev/dri"]         # bwrap --dir targets
[[sandbox.bind]]      src=, dst=, mode=(ro|rw|dev|dev-bind), create=bool
[[sandbox.bind_try]]  ...             # conditional (skipped if src absent)
[sandbox.env]         KEY = "val"     # $VAR expanded

create = true on a bind mkdir's its (expanded) src before bwrap, so a required state-dir bind (e.g. $BUBBLEBOX_DATA_DIR/<pkg> -> /persist) materializes itself instead of failing.

Tools with no special sandbox needs (rg, fd, bat, ...) ship no entrypoint.toml — bubblebox run <name> synthesizes a default { package = <name> } when none is present.

The override layer lives outside this repo, at ~/.config/bubblebox/entrypoints/<pkg>.toml, and deep-merges over the default at run time. See the engine's AGENTS.md ("Override layering & deep-merge") for the full merge rules.

Adding a package

1. Drop a <name>/ subdir with a Containerfile (and, if the tool needs binds/env, an entrypoint.toml).
2. Add <name> to the consuming host's profile.toml packages list.
3. bubblebox build <name> (or the host's cjust bubblebox-build <name>).