# GSoC 2026 Discussion Draft - Unified Sandbox Driver Architecture (Idea #10)

[dhunganapramod9]

Hi everyone - I’m planning to apply for Idea 10: Unified Sandbox Driver
Architecture and wanted to start a concrete technical discussion early so I
can align scope and design with maintainers before implementation.

I’ve been studying the current sandbox paths in Gemini CLI and my current
understanding is:

• Sandbox selection is resolved in CLI config using command literals (docker,
  podman, sandbox-exec) and env/settings precedence.
• Runtime orchestration is concentrated in a large sandbox entrypoint that
  handles platform branching, image checks/pulls, mounts, proxy sidecars, and
  process lifecycle.
• Prompt sandbox messaging in core currently depends on environment state.
• There is also script-level sandbox command resolution logic that can drift
  from runtime behavior.

For context on execution fit: I’ve already done similar architecture work in
NightShift CLI, where my merged PR (nightshiftco/nightshift#114) focused on cross-platform CLI
behavior and abstraction boundaries - the same kind of separation this sandbox
driver refactor needs (platform strategy isolation + centralized orchestration
contracts).

Based on that, I’m proposing a driver-based architecture in
@google/gemini-cli-core with:

1. A typed SandboxDriver interface (isAvailable, preflight,
   createLaunchPlan, cleanup).
2. A SandboxLifecycleManager that owns discovery, selection, diagnostics, and
   sidecar/process supervision.
3. Driver implementations for:
   • macOS Seatbelt,
   • Docker,
   • Podman,
   • No-Op fallback (with explicit warnings/diagnostics).
4. A typed runtime sandbox context that prompt/telemetry paths can consume
   instead of inferring from env directly.
5. A migration strategy that preserves behavior via parity tests while
   extracting logic incrementally.

Initial scope I’m targeting

• In-scope

  • Define the driver/lifecycle contracts in core.
  • Refactor Seatbelt + Docker/Podman paths behind those contracts.
  • Add No-Op driver and deterministic fallback diagnostics.
  • Add unit tests per driver and lifecycle selection tests.
  • Add/adjust integration coverage for driver-mode parity.

• Out-of-scope (for this GSoC cycle)

  • Full Bubblewrap implementation.
  • Full Windows AppContainer implementation.
  • Major policy rewrites of existing Seatbelt profiles.

Open questions I’d really value maintainer guidance on

1. Should the driver registry/discovery policy live entirely in core, or do
   you prefer a thin CLI-layer resolver that passes an explicit driver ID to
   core?
2. For migration safety, do maintainers prefer:
   • (A) introducing the new lifecycle path behind a feature flag first, then
     flipping default, or
   • (B) direct replacement with strict parity tests?
3. For diagnostics surfaced to users, do you prefer a structured error code
   model exposed in logs/output, or a simpler human-readable warning model
   first?
4. Is there any known internal work/plans around sandbox abstractions that I
   should align with before drafting final interface names?

---

@taylormullen - I’d really appreciate your input on whether this
architecture direction matches what you want for Idea #10, especially around:

• where you want ownership boundaries between CLI and core,
• expected migration strategy (flagged vs direct), and
• minimum acceptable test matrix before merging driver extraction PRs.

If this direction is aligned, I can post a short RFC-style follow-up with exact
proposed interfaces and a week-by-week implementation breakdown for review.

[dipeshbabu]

Solid Proposal! The driver-based architecture makes a lot of sense, and the migration plan looks practical. Excited to see this move forward.

[dhunganapramod9]

Thank you, Dipeshbabu!