Use case · Gemini CLI · Updated 2026-10-31
Run Gemini CLI in a microVM on your Mac or Linux machine.
A Gemini CLI sandbox keeps Google's coding agent away from everything on your computer except the project it is working on. kosa8's built-in gemini kit runs Gemini CLI in its own microVM: it sees one folder, its network is closed except through a broker on your side, and the sandbox holds a placeholder instead of your Gemini API key. Start it with kosa8 agent run gemini.
01What does Gemini CLI's own sandbox do?
Gemini CLI can sandbox itself. You turn it on with -s/--sandbox, with GEMINI_SANDBOX=true|docker|podman|sandbox-exec|runsc|lxc, or with "sandbox": true in settings.json. On macOS the lightweight option is Seatbelt (sandbox-exec); the container option uses Docker or Podman with the ghcr.io/google/gemini-cli image.
kosa8 tested GEMINI_SANDBOX=docker against its Docker-compatible API with Gemini CLI 0.64.0, and it does not work on Apple silicon yet: the sandbox image is published for linux/amd64 only, so the container fails with Exec format error. It also bind-mounts ~/.config/gcloud. The gemini kit avoids both by running Gemini CLI itself inside the microVM.
02The built-in gemini kit
kosa8 agent run gemini starts a microVM from node:22-alpine with 4 vCPUs and 4096 MiB, installs @google/gemini-cli pinned to 0.64.0 and checked against its SHA-512 digest, mounts your current folder at /work and runs gemini there. It is removed when Gemini CLI exits.
03Your Gemini API key stays on your computer
The sandbox gets GEMINI_API_KEY set to a placeholder and GOOGLE_GEMINI_BASE_URL pointed at an egress broker on your side, which adds the real key, in the x-goog-api-key header, only to requests for generativelanguage.googleapis.com. Apart from the broker, the kit allows registry.npmjs.org and nothing else.
04Audit log and an emergency stop
Every request through the broker, allowed or refused, goes into kosa8's hash-chained audit log. kosa8 sandbox pause --all freezes every running agent mid-step with its memory and files intact.
kosa8 audit ls kosa8 sandbox pause --all
05Pin a different version
To pin another Gemini CLI release, write the kit to a file, change the version and its integrity (from npm view), and preview it.
kosa8 agent init gemini npm view @google/[email protected] dist.integrity kosa8 agent run --dry-run gemini
06How to start
Install kosa8 and start its daemon.
Set your key on your computer and run Gemini CLI in your project.
export GEMINI_API_KEY=... kosa8 agent run --dry-run gemini kosa8 agent run gemini
07Questions
Can I use GEMINI_SANDBOX=docker with kosa8?
Not on Apple silicon yet. kosa8 tested it with Gemini CLI 0.64.0: the sandbox image is published for linux/amd64 only, so on an arm64 Mac it fails with Exec format error. Use the gemini kit, which runs Gemini CLI itself in the microVM.
Does the gemini kit hold my Gemini API key?
No. The sandbox holds a placeholder, and a broker on your computer adds the real key only to requests for generativelanguage.googleapis.com. The kit brokers GEMINI_API_KEY; signing in with a Google account is not covered by the kit.
What can Gemini CLI see inside the sandbox?
The folder you share, mounted at /work, and nothing else on your computer. It can change anything in that folder, including .git, so commit first.
Which machines can run it?
kosa8 runs its microVMs on an Apple silicon Mac (Apple's Virtualization framework) or on x86-64 Linux (KVM). On an Intel Mac it installs as the command-line tool only and drives sandboxes on one of those machines.
08Guides and articles
09Sources
10Try it on your own machine
Install kosa8 and run Gemini CLI in a machine of its own, with the key kept outside.
Updated 2026-10-31