feat(run-prompt): add --sandbox bubblewrap for Linux prompt execution

[cruzanstx]

Summary

Add first-class Bubblewrap execution to /run-prompt so Linux users can run prompts with one flag instead of writing custom bwrap wrappers.

Proposed UX

• /run-prompt <id> --sandbox bubblewrap
• Optional: --sandbox-profile strict|balanced|dev
• Optional: --sandbox-workspace <path>
• Optional: --sandbox-net on|off

Why

Linux users need a lightweight sandbox path comparable to seatbelt-style workflows on macOS, without forcing Docker/Podman. Bubblewrap works well but policy setup is error-prone when done manually.

Behavior expectations

• Auto-detect bwrap and run prompt in a generated policy wrapper
• Safe defaults by profile:
  • strict: minimal RW mounts, no net by default
  • balanced: project RW + required cache/config/state dirs, net enabled
  • dev: wider compatibility for plugin-heavy/dev workflows
• Include --new-session and secure defaults around terminal injection concerns
• Clear warnings for high-risk mounts (broad HOME, D-Bus sockets, etc.)

Failure handling

• If bwrap is missing, show install hint and fail with actionable guidance
• Optional explicit fallback flag if user wants to run unsandboxed

Acceptance criteria

• Linux user can run /run-prompt <id> --sandbox bubblewrap without manual script authoring
• Profiles are documented with tradeoffs
• Strict profile blocks access outside allowed workspaces
• Balanced/dev profiles keep common agent workflows functional
• Troubleshooting docs cover missing certs/DNS binds/userns constraints

References

• Bubblewrap upstream: https://github.com/containers/bubblewrap
• bwrap man page: https://manpages.debian.org/testing/bubblewrap/bwrap.1.en.html
• OpenCode sandbox discussion: Is there a way to sandbox the agent ? anomalyco/opencode#2242 (comment)

[cruzanstx]

Love this direction — here's a concrete MVP sketch that keeps UX simple and implementation incremental.

Proposed CLI contract

• --sandbox → enable sandboxing
• --sandbox-type <type> → optional backend override
• --no-sandbox → explicit opt-out

Default behavior:

• On Linux, --sandbox without --sandbox-type defaults to bubblewrap.
• If sandboxing is enabled and backend is omitted, resolve from platform defaults.

Examples:

• /run-prompt 257 --sandbox
• /run-prompt 257 --sandbox --sandbox-type bubblewrap
• /run-prompt 257 --no-sandbox

MVP implementation plan

1) Arg parsing

Add/normalize flags in run-prompt:

• sandbox: boolean | undefined
• sandboxType: string | undefined
• sandboxProfile: strict|balanced|dev (optional, default balanced)
• sandboxWorkspace: string | undefined
• sandboxNet: on|off (optional)

Validation rules:

• Error if both --sandbox and --no-sandbox are passed.
• Error if --sandbox-type is provided while sandboxing is disabled.
• Resolve defaults:
  • if sandbox === true and no type:
    • linux → bubblewrap
    • others → existing/no-op backend behavior

2) Sandbox resolver

Create a small resolver:

resolveSandboxConfig({ platform, flags, cwd, env }) -> { enabled, type, profile, workspace, network }

Responsibilities:

• default profile to balanced
• workspace default to current repo/workdir
• network default by profile (strict=off, balanced/dev=on)

3) Bubblewrap backend (MVP)

Implement runWithBubblewrap(config, childCommand):

• preflight checks:
  • bwrap present (command -v bwrap)
  • workspace exists
  • required dirs exist or can be created
• generate argument list (not shell string concat):
  • --unshare-all
  • --new-session
  • --die-with-parent
  • --share-net iff network on
  • readonly system binds (/usr, /bin, /lib*, certs, resolv/hosts)
  • rw binds for workspace + tool state/cache/config dirs
  • tmpfs for /tmp//run
• spawn child process with inherited stdio
• propagate exact exit code

4) Profile presets (hardcoded table first)

const BWRAP_PROFILES = {
  strict: { net: false, writable: [workspace, opencodeState], minimalEnv: true },
  balanced: { net: true, writable: [workspace, opencodeState, opencodeCache, opencodeConfig], minimalEnv: true },
  dev: { net: true, writable: [workspace, opencodeState, opencodeCache, opencodeConfig, toolCaches], minimalEnv: false },
}

Start with static presets; move to config file later.

5) Error handling UX

If bwrap missing:

• Fail with actionable message and install hints (apt/dnf/pacman examples).
• Suggest --no-sandbox if user explicitly wants to continue unsandboxed.

If launch fails:

• Print generated backend config summary (type/profile/workspace/net)
• return non-zero with concise remediation hints.

Minimal file layout suggestion

• src/commands/run-prompt.ts (flag parsing + orchestration)
• src/sandbox/resolve.ts (default resolution)
• src/sandbox/backends/bubblewrap.ts (backend executor)
• src/sandbox/profiles/bubblewrap.ts (profile table)

Test plan (MVP)

• Unit: resolver defaults/validation matrix
• Unit: bubblewrap arg builder per profile
• Integration (linux CI):
  • --sandbox resolves to bubblewrap
  • prompt executes and returns child exit code
  • --sandbox-type bubblewrap works
  • conflicting flags fail as expected

This gets us to a useful v1 quickly while keeping room for future sandbox backends.