GSoC 2026 – Interest in Unified Sandbox Driver Architecture (Idea #10)

[GoBeromsu]

Hi everyone,

My name is Beomsu Koh. I recently completed an MSc in Computer Science at the University of Sheffield and I’m currently exploring the Gemini CLI repository as I prepare for GSoC 2026.

I’m particularly interested in Idea 10 — Unified Sandbox Driver Architecture. I enjoy refactoring and system design work, and this idea touches exactly that — cross-platform abstraction, architecture design, and security boundaries.

At the moment I’m reading through the codebase and fixing bugs I encounter along the way:

• Issue: start.js: signal death silently exits with code 0 #21086
• PR: fix(scripts): handle signal death and null exit code in start.js #21087

I wanted to introduce myself and start a discussion thread as I dig deeper into the sandbox implementation.

I’ll continue exploring the relevant modules and will post updates here as I build a clearer understanding of the current architecture and potential directions for Idea 10.

Thanks!

[aniruddhaadak80]

From my point of view, this is the right kind of early approach for Idea 10 because it starts from the current code and one concrete issue rather than jumping straight to abstraction. The thing I would prioritize while exploring is a small capability map of what each sandbox backend actually guarantees today around filesystem, network, and process behavior. Once that is written down, the driver architecture becomes much easier to design without hiding important platform differences.

[GoBeromsu]

Thanks for the suggestion on the capability map — that's a valid point since we're dealing with sandbox backends that guarantee very different things at the OS level.

Current structure

I've been reading through the sandbox-related files (there are about 5 clustered under cli/src/utils/ and cli/src/config/) and also went through docs/cli/sandbox.md. The docs list 4 sandboxing methods (Seatbelt, Docker/Podman, gVisor/runsc, LXC), but the code uses guard clauses with early returns for Seatbelt and LXC, then falls through to the container path where runsc and podman are handled as sub-branches:

flowchart TD
    SS["start_sandbox()"] --> SB{"sandbox-exec?"}
    SB -->|Yes| Seatbelt["Seatbelt (macOS)<br/>return early"]
    SB -->|No| LX{"lxc?"}
    LX -->|Yes| LXC["LXC/LXD (Linux)<br/>return early"]
    LX -->|No| CT["Container path<br/>(fall-through)"]
    CT --> R{"runsc?"}
    R -->|Yes| Runsc["command = docker<br/>+ --runtime=runsc"]
    R -->|No| DP{"podman?"}
    DP -->|Yes| Podman["docker + --authfile"]
    DP -->|No| Docker["docker (as-is)"]

Loading

All paths follow roughly the same 5-phase pattern:

1. Validate (profile exists? image present? container running?)
2. Configure environment (this is where they diverge the most)
3. Proxy setup (Seatbelt and Container only — LXC doesn't need this)
4. Spawn process + await exit code (nearly identical across all three)
5. Cleanup (proxy kill, container rm, or device remove)

How to split the container path?

I think having 4 drivers matching the docs (Seatbelt, Docker/Podman, gVisor/runsc, LXC) makes sense — but the container path is tricky because runsc only differs by one line at L287 (args.push('--runtime=runsc')) and Podman by a few lines at L609-612 (creates an empty auth file and passes --authfile). With that little difference, I'm leaning toward a base ContainerDriver with thin subclasses that only override those lines. Does that direction make sense, or would you structure it differently?

I'll also work on a capability map covering filesystem, network, and process behavior for each backend — understanding what each actually guarantees seems like the right foundation before designing abstractions.

cc @NTaylorMullen