claudebox/.planning/research/FEATURES.md

Feature Landscape

Domain: CLI sandbox wrapper (Nix/bubblewrap) for AI coding agents Researched: 2026-04-09 Confidence: MEDIUM (based on training data for firejail, bubblejail, nixpak, bwrap; web verification unavailable)

Reference Projects Surveyed

Project	Approach	Relevance to claudebox
firejail	SUID sandbox with 1000+ app profiles, seccomp, caps, filesystem overlays	Gold standard for feature breadth; overkill for claudebox's scope
bubblejail	Python wrapper around bwrap with service-based profiles (DBus, Pulse, GPU, etc.)	Closest UX model -- wraps bwrap with declarative config
nixpak	Nix module system for generating bwrap-wrapped Nix packages	Closest tech model -- Nix-native bwrap wrapping
nix-bubblewrap	Simple Nix functions for bwrap wrapping	Minimal reference for the Nix derivation approach
flatpak	Full container runtime with portals	Portal concept (controlled host access) is relevant

Table Stakes

Features users expect. Missing = the wrapper is broken or useless for its stated purpose (secrets isolation for AI agents).

Feature	Why Expected	Complexity	Notes
Filesystem isolation	Core value proposition -- secrets must be invisible	Low	bwrap --ro-bind, --bind, --tmpfs for mount control. CWD read-write, everything else denied or read-only
Environment allowlist	Denylist misses unknown vars; allowlist is secure-by-default	Low	--clearenv + explicit --setenv per var. All sandbox tools do this
Secret path hiding	~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, age keys, Tailscale state must never be visible	Low	Simply don't mount them. With bwrap's default deny, this is the natural state
Minimal PATH	Prevent access to host tools that might leak info or have side effects	Low	Construct PATH from explicit Nix store paths only
Nix store read-only mount	Required for nix shell and comma to work inside sandbox	Low	--ro-bind /nix/store /nix/store
Persistent config directory	Claude Code needs ~/.claude to persist auth, settings, conversation state	Low	Bind-mount ~/.claudebox as ~/.claude inside sandbox
Pre-launch env audit	User must see exactly what enters the sandbox before launch	Low	Print env vars, prompt for confirmation. --yes/-y to skip
Working /tmp	Many tools need tmpdir; Claude Code writes temp files	Low	--tmpfs /tmp
Working /dev basics	/dev/null, /dev/urandom, /dev/zero needed by most programs	Low	bwrap --dev /dev provides these
Proc filesystem	Node.js (Claude Code runtime) needs /proc for process info	Low	--proc /proc
Exit code passthrough	Wrapper must forward the wrapped command's exit code	Low	exec bwrap ... claude handles this
Signal forwarding	Ctrl+C must reach Claude Code, not just kill the wrapper	Low	exec makes this automatic; no intermediate shell

Differentiators

Features that set claudebox apart from generic sandbox wrappers. Not expected in a basic bwrap wrapper, but valuable for the AI agent use case.

Feature	Value Proposition	Complexity	Notes
Tool self-provisioning via comma	Claude can nix shell or , <tool> to get any dev tool on demand without pre-declaration	Low	Already planned. Unique to Nix-based sandboxes. No other sandbox tool has this
Injected system prompt	Claude knows it's sandboxed, knows how to use comma/nix for tools, behaves accordingly	Low	CLAUDE_SYSTEM_PROMPT or ~/.claudebox/CLAUDE.md
Env var leak detection	Scan env vars for patterns that look like secrets (API keys, tokens, passwords) and warn even if they're on the allowlist	Medium	Regex scan for .*KEY.*, .*TOKEN.*, .*SECRET.*, .*PASSWORD.*, base64-ish strings. Firejail does similar with --private-etc
Mount audit log	Log exactly what paths are mounted and how (ro/rw) for post-hoc review	Low	Print mount table at launch (behind --verbose flag)
Project-local tool declarations	.claudebox.toml or .claudebox/tools.txt in project root listing extra Nix packages to pre-install	Medium	Deferred per PROJECT.md, but the hook point should exist
Dry-run mode	--dry-run prints the full bwrap command without executing	Low	Debugging aid. firejail has --debug; bubblejail has similar
Multiple working directories	Mount additional paths read-only or read-write beyond CWD	Low	--mount-ro /path and --mount-rw /path flags
Git credential isolation	Provide git with a sandbox-specific credential helper or .gitconfig so Claude can push without accessing host SSH keys	Medium	Mount a sandbox .gitconfig with only HTTPS credential helpers; never SSH agent
Sandbox health check	claudebox --check verifies bwrap works, required Nix packages exist, config dir is set up	Low	Good onboarding UX

Anti-Features

Features to deliberately NOT build. Either out of scope, security risks, or wrong layer.

Anti-Feature	Why Avoid	What to Do Instead
Network isolation / firewall	Claude Code already has domain allowlisting via its proxy. Network filtering in bwrap is fragile (needs netns, slirp4netns). Wrong layer	Trust Claude Code's built-in network controls
GUI / X11 / Wayland passthrough	Claude Code is a CLI tool. Mounting display sockets opens a massive attack surface for zero benefit	Don't mount any display sockets
Audio / PulseAudio / PipeWire	No audio needed for a coding agent	Don't mount audio sockets
DBus access	No desktop integration needed. DBus is a common sandbox escape vector	Don't mount DBus sockets
Configurable security profiles	v1 is one hardcoded security posture. Profiles add complexity and misconfiguration risk. Firejail's profile system is a maintenance burden	One secure default. Profiles in a later version if needed
Seccomp syscall filtering	bwrap's namespace isolation is sufficient for the threat model (AI agent leaking secrets, not malicious binary exploitation). Seccomp adds complexity and breaks tools unpredictably	Rely on filesystem/env isolation. Add seccomp only if threat model changes
Capability dropping	Same reasoning as seccomp -- the threat is data exfiltration via the agent, not privilege escalation	bwrap already drops caps by default in user namespaces
Persistent overlay filesystem	Flatpak-style overlay FS adds complexity. A simple bind mount for ~/.claudebox is sufficient	Use bind mounts
Docker/OCI container wrapping	Nix + bwrap is lighter, faster, and doesn't need a daemon	Stay with bwrap
Automatic updates / self-update	This is a Nix derivation. Updates come through the flake	Use nix flake update
Remote/distributed sandboxing	This runs on one machine (endurance). No need for remote execution	Out of scope
Permission prompting inside sandbox	--dangerously-skip-permissions is deliberate -- bwrap IS the permission layer. Adding prompts back would be redundant and annoying	The sandbox boundary replaces Claude's permission prompts

Feature Dependencies

Filesystem isolation ─┐
Environment allowlist ─┤
Secret path hiding ────┤
Minimal PATH ──────────┼── Core sandbox (all required together)
Nix store mount ───────┤
Working /tmp,/dev,/proc┘

Nix store mount ──────── Tool self-provisioning (comma)
                          └── Project-local tool declarations (future)

Pre-launch env audit ─── Env var leak detection (enhancement of audit)

Persistent config dir ── Injected system prompt (lives in config dir)

Core sandbox ─────────── Dry-run mode (needs bwrap command assembled first)
Core sandbox ─────────── Mount audit log (needs mount list)
Core sandbox ─────────── Sandbox health check (validates core works)

Multiple working dirs ── Independent (optional mount flag)
Git credential isolation ── Independent (optional .gitconfig mount)

MVP Recommendation

Prioritize for v1:

1. Core sandbox (all table stakes) -- this is the entire point
2. Tool self-provisioning via comma -- already planned, low complexity, high value
3. Injected system prompt -- low complexity, dramatically improves Claude's behavior in the sandbox
4. Pre-launch env audit with --yes flag -- already planned, essential UX
5. Dry-run mode -- trivial to implement, invaluable for debugging

Defer:

• Env var leak detection: Nice but not critical for v1 since the allowlist is hand-curated anyway
• Project-local tool declarations: Explicitly deferred in PROJECT.md
• Git credential isolation: Complex edge case; can be added when needed
• Multiple working directories: Can be added as a flag later without architectural changes
• Mount audit log: Low priority, --dry-run covers most of this need

Lessons from Reference Projects

From firejail

• Profiles are a maintenance nightmare. Firejail maintains 1000+ profiles and they constantly break on updates. claudebox should have ONE hardcoded config.
• Allowlist beats denylist. Firejail's --whitelist is more secure than its --blacklist. claudebox already chose this correctly.
• --quiet and --debug flags matter. Users want silence by default and verbosity on demand.

From bubblejail

• Service-based decomposition is elegant but overkill. Bubblejail breaks permissions into "services" (Network, Audio, GPU, etc.). For a single-purpose tool, this is unnecessary complexity.
• Desktop file generation is a nice touch for GUI apps, but irrelevant for CLI.

From nixpak

• Nix module system for bwrap config is powerful but adds abstraction. For a personal tool, a writeShellApplication with inline bwrap args is simpler and more transparent.
• Sloth (nixpak's helper) provides a nice API for filesystem permissions. Worth looking at the mount specification approach even if not using the library directly.
• FHS compatibility layer is available but not needed -- Claude Code runs from Nix store.

From flatpak

• Portals (controlled access to host resources via DBus) are the right idea but wrong mechanism for CLI. The equivalent for claudebox is explicit mount flags.
• "No access by default, grant explicitly" is the correct security model and claudebox follows it.

Sources

• firejail documentation and features page (training data, HIGH confidence for feature list -- firejail is well-documented and stable)
• bubblejail GitHub repository (training data, MEDIUM confidence -- less popular project)
• nixpak GitHub repository and NixOS discourse discussions (training data, MEDIUM confidence)
• bubblewrap man page and documentation (training data, HIGH confidence -- stable API)
• flatpak documentation on sandboxing and portals (training data, HIGH confidence)

Note: Web search and fetch were unavailable during this research session. All findings are based on training data. The core features of these tools (bwrap flags, firejail profiles, nixpak architecture) are stable and well-established, so confidence remains reasonable despite the inability to verify against current sources.