Skip to content

Sandbox / bnerd isolate

Manage the AI sandbox runtime used by the --isolate global flag.

The --isolate flag (on bnerd x and bnerd mcp-server) re-executes the process inside a filesystem-isolated environment so the AI cannot read or write outside the current working directory plus a small allowlist of credential files. The bnerd isolate subcommands diagnose and manage the runtime that powers it.

For the threat model, mount table, and usage walkthrough, see the AI sandbox guide.

Diagnose

bnerd isolate doctor

Reports which runtime would be selected (bubblewrap → podman → docker priority), what mounts apply for --isolate=on and --isolate=strict, whether the container image is cached (podman/docker only), and whether a TTY is available for the TUI.

Run this first when troubleshooting --isolate behavior.

Build the container image

bnerd isolate build

Builds the bnerd-isolate:v<version> image used by the podman/docker fallback runtimes. No-op when bubblewrap is selected (bwrap inherits the host PATH and needs no image).

Prune the cached image

bnerd isolate prune

Removes the cached bnerd-isolate:v<version> image. No-op when bubblewrap is selected.

Run a subcommand explicitly

bnerd isolate run -- <bnerd subcommand and args>

Equivalent to bnerd --isolate <args> but useful in shell scripts where flag parsing is awkward. Use -- to separate the isolate run flags from the inner subcommand's flags.

Flags

Flag Type Default Description
--strict bool false Use --isolate=strict (omit ~/.kube/config from mounts)

If the process is already running inside isolation (BNERD_IN_ISOLATE=1), isolate run exec's the requested command in the existing sandbox instead of double-wrapping.

Runtime selection

--isolate picks the first available runtime in this order:

  1. bubblewrap (bwrap) — preferred on Linux. ~50 ms cold start, no daemon, host PATH inherited.
  2. podman — used when bwrap is unavailable.
  3. docker — universal fallback.

Override defaults are not exposed today; install whichever runtime you prefer at the front of the priority list. See the sandbox guide for install instructions per platform.

Examples

# First-time check before using --isolate
bnerd isolate doctor

# Pre-build the image so the first --isolate invocation isn't slow
bnerd isolate build

# Run the TUI under isolation
bnerd --isolate x

# Strict mode (drops kubeconfig) for an untrusted local model
bnerd --isolate=strict x

# Equivalent via isolate run
bnerd isolate run -- x
bnerd isolate run --strict -- mcp-server --read-only

See also