improve sandboxing status message, update README, remove dead code from a previous change to build_sandbox.sh (#346)

This commit is contained in:
Olcan 2025-05-14 11:23:06 -07:00 committed by GitHub
parent bfda4295c9
commit 1fa40405ea
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 13 additions and 14 deletions

View File

@ -106,13 +106,15 @@ Chances are you will need to manually address errors output. You can also try `n
## Sandboxing
To enable sandboxing, set `GEMINI_CODE_SANDBOX=true|docker|podman|<command>` in your environment or `.env` file. Once enabled, `npm run build:all` will build a minimal container ("sandbox") image and `npm start` will launch inside a fresh instance of that container. Requires the specified command (or if `true` then either `docker` or `podman`) to be available on host machine.
On MacOS, `gemini` uses Seatbelt (`sandbox-exec`) under a `minimal` profile (see `packages/cli/src/utils/sandbox-macos-minimal.sb`) that restricts writes to the project folder but otherwise allows all other operations by default. You can switch to a `strict` profile (see `.../sandbox-macos-strict.sb`) that declines operations by default by setting `SEATBELT_PROFILE=strict` in your environment or `.env` file. You can also switch to a custom profile `SEATBELT_PROFILE=<profile>` if you also create a file `.gemini/sandbox-macos-<profile>.sb` under your project settings directory `.gemini`.
The sandbox (container) mounts the current directory with read-write access and is started/stopped/removed automatically as you start/stop Gemini Code. You can tell you are inside the sandbox with the `cwd` being reported as `/sandbox/<project>`. Files created within the sandbox should be automatically mapped to your user/group on host machine.
For stronger container-based sandboxing on MacOS or other platforms, you can set `GEMINI_CODE_SANDBOX=true|docker|podman|<command>` in your environment or `.env` file. The specified command (or if `true` then either `docker` or `podman`) must be installed on the host machine. Once enabled, `npm run build:all` will build a minimal container ("sandbox") image and `npm start` will launch inside a fresh instance of that container. The first build can take 20-30s (mostly due to downloading of the base image) but after that both build and start overhead should be minimal. Default builds (`npm run build`) will not rebuild the sandbox.
The very first build of the container (with `npm run build` or `scripts/build_sandbox.sh`) can take 20-30s (mostly due to downloading of the base image) but after that both build and start overhead should be minimal (1-2s).
Container-based sandboxing mounts the project directory (and system temp directory) with read-write access and is started/stopped/removed automatically as you start/stop Gemini Code. Files created within the sandbox should be automatically mapped to your user/group on host machine. You can easily specify additional mounts, ports, or environment variables by setting `SANDBOX_{MOUNTS,PORTS,ENV}` as needed. You can also fully customize the sandbox for your projects by creating the files `.gemini/sandbox.Dockerfile` and/or `.gemini/sandbox.bashrc` under your project settings directory `.gemini`.
You can customize the sandbox in `Dockerfile` (e.g. for pre-installed utilities) or in `scripts/build_sandbox.sh` (e.g. for mounts `-v ...`, ports `-p ...`, or environment variables `-e ...`) and any changes should be automatically picked up by `npm run build` and `npm start` respectively.
### Attaching from VSCode
With container-based sandboxing, you can have VSCode (or forks like Cursor) attach to a running sandbox container using the [Dev Containers](https://marketplace.cursorapi.com/items?itemName=ms-vscode-remote.remote-containers) extension. Simply use `Dev Containers: Attach to Running Container ...` command and select your container named `...-sandbox-#`. Sandbox container name should be displayed in green at the bottom in terminal when running `gemini`. You may need to set the VSCode setting `dev.containers.dockerPath` (e.g. to `podman`) if you are not using Docker, and otherwise you may be prompted by the extension to install Docker if missing from your system.
## Manual Publish
@ -125,7 +127,3 @@ npm run auth
npm run prerelease:dev
npm publish --workspaces
```
### Attaching from VSCode
You can have VSCode (or forks) attach to a running sandbox using the [Dev Containers](https://marketplace.cursorapi.com/items?itemName=ms-vscode-remote.remote-containers) extension. Simply use `Dev Containers: Attach to Running Container ...` command and select your container named `gemini-code-sandbox-#`. Once attached you can open the project folder at `/sandbox/<project>`. You may need to set the VSCode setting `dev.containers.dockerPath` (e.g. to `podman`) if you are not using Docker, and otherwise you may be prompted by the extension to install Docker if missing from your system.

View File

@ -46,13 +46,15 @@ export const Footer: React.FC<FooterProps> = ({
display="flex"
>
{process.env.SANDBOX && process.env.SANDBOX !== 'sandbox-exec' ? (
<Text color="green"> {process.env.SANDBOX} </Text>
<Text color="green">
{process.env.SANDBOX.replace(/^gemini-(?:code-)?/, '')}
</Text>
) : process.env.SANDBOX === 'sandbox-exec' ? (
<Text color={Colors.AccentYellow}>
using macos seatbelt ({process.env.SEATBELT_PROFILE})
sandbox-exec ({process.env.SEATBELT_PROFILE})
</Text>
) : (
<Text color={Colors.AccentRed}> WARNING: OUTSIDE SANDBOX </Text>
<Text color={Colors.AccentRed}>no sandbox (see README)</Text>
)}
</Box>

View File

@ -27,16 +27,15 @@ IMAGE=gemini-code-sandbox
DOCKERFILE=Dockerfile
SKIP_NPM_INSTALL_BUILD=false
while getopts "sdf:" opt; do
while getopts "sf:" opt; do
case ${opt} in
s) SKIP_NPM_INSTALL_BUILD=true ;;
f)
DOCKERFILE=$OPTARG
;;
\?)
echo "usage: $(basename "$0") [-s] [-d] [-f <dockerfile>]"
echo "usage: $(basename "$0") [-s] [-f <dockerfile>]"
echo " -s: skip npm install + npm run build"
echo " -d: build dev image (use Dockerfile-dev)"
echo " -f <dockerfile>: use <dockerfile>"
exit 1
;;