jcarr
/
gemini-cli
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fixes and tweaks to docs, mostly related to sandboxing (#385)

This commit is contained in:
Olcan 2025-05-16 13:09:27 -07:00 committed by GitHub
parent c692a0c583
commit 1728bf3f44
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 22 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -17,7 +17,7 @@ The Gemini CLI supports several ways to authenticate with Google's AI services.
```bash
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```
Or add it to your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`) for persistence:
Or add it to your `.env` file (in project directory or user home) or shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`) for persistence:
```bash
echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc # Or your preferred shell config file
source ~/.bashrc # Reload the config

35
docs/cli/configuration.md
View File

@ -25,22 +25,13 @@ The Gemini CLI uses `settings.json` files for persistent configuration. There ar
### The `.gemini` Directory in Your Project
When you create a `.gemini/settings.json` file for project-specific settings, or when the system needs to store project-specific information (like custom Seatbelt profiles, e.g., `.gemini/sandbox-macos-custom.sb`), this `.gemini` directory is used.
When you create a `.gemini/settings.json` file for project-specific settings, or when the system needs to store project-specific information (like custom sandboxing profiles, e.g., `.gemini/sandbox-macos-custom.sb` or `.gemini/sandbox.Dockerfile`), this `.gemini` directory is used.
**Purpose:**
- Stores project-specific configuration for the Gemini CLI (in `settings.json`).
- Can hold other project-specific files related to Gemini CLI's operation, such as custom sandbox profiles.
**Version Control (`.gitignore`):**
- **Generally, it's recommended to add `.gemini/` to your project's `.gitignore` file.**
- **Reasoning:** This directory often contains user-specific preferences (like themes) or local sandbox configurations that might not be relevant or applicable to all collaborators on the project. Keeping it out of version control avoids imposing one user's local setup on others.
- **Exception:** If your team decides that certain project-specific configurations within `.gemini/` (e.g., a carefully crafted `sandbox-macos-custom.sb` profile that _all_ macOS users on the project should use) are essential for consistent project behavior, you might choose to commit specific files within `.gemini/` (e.g., `.gemini/sandbox-macos-custom.sb`) or the entire directory. However, this should be a deliberate decision by the team.
- User-specific `settings.json` often contains local paths or preferences that should not be committed.
Always consider the nature of the files within `.gemini/` before deciding to include them in version control. For most common use cases, ignoring the entire directory is the safest approach.
### Available Settings in `settings.json`:
- **`theme`** (string):
@ -49,17 +40,19 @@ Always consider the nature of the files within `.gemini/` before deciding to inc
- See the [Theming section in README.md](../../README.md#theming) for available theme names.
- **`sandbox`** (boolean or string):
- Controls whether and how to use sandboxing for tool execution.
- `true`: Enable default sandbox (e.g., Docker or Podman if configured, otherwise OS-level like Seatbelt on macOS).
- `false`: Disable sandboxing (less secure).
- `"docker"` or `"podman"`: Explicitly choose container-based sandboxing.
- `<command>`: Specify a custom command for sandboxing.
- Example: `"sandbox": true`
- `true`: Enable default sandbox (see [README](../../README.md) for behavior).
- `false`: Disable sandboxing (WARNING: this is inherently unsafe).
- `"docker"` or `"podman"`: Explicitly choose container-based sandboxing command.
- `<command>`: Specify custom command for container-based sandboxing.
- **`toolDiscoveryCommand`** (string, advanced):
- Custom command for tool discovery (if applicable to your setup).
- Must return JSON array of tools of `function_declarations` type as in [Gemini REST API](https://ai.google.dev/gemini-api/docs/function-calling).
- **`toolCallCommand`** (string, advanced):
- Custom command for executing tool calls (if applicable to your setup).
- Must take function name as first argument and function arguments as JSON on `stdin`
- Must return JSON result of funcation call on `stdout`.
- **`mcpServerCommand`** (string, advanced):
- Custom command for the MCP (Multi-Context Prompt) server (if applicable).
- Custom command for starting an MCP server with custom tools.
### Example `settings.json`:
@ -67,9 +60,9 @@ Always consider the nature of the files within `.gemini/` before deciding to inc
{
"theme": "VS2015",
"sandbox": "docker",
"toolDiscoveryCommand": "/usr/local/bin/my-custom-tool-discovery --json",
"toolCallCommand": "/usr/local/bin/my-custom-tool-executor",
"mcpServerCommand": "node /opt/mcp-server/dist/server.js --port 8080"
"toolDiscoveryCommand": "bin/get_tools",
"toolCallCommand": "bin/call_tool",
"mcpServerCommand": "bin/mcp_server.py"
}
```
@ -96,8 +89,8 @@ The CLI automatically loads environment variables from an `.env` file. The loadi
- Accepts `true`, `false`, `docker`, `podman`, or a custom command string.
- **`SEATBELT_PROFILE`** (macOS specific):
- Switches the Seatbelt (`sandbox-exec`) profile on macOS.
- `minimal`: (Default) Restricts writes to the project folder but allows other operations.
- `strict`: Uses a more restrictive profile that declines operations by default.
- `minimal`: (Default) Restricts writes to the project folder (and a few other folders, see `packages/cli/src/utils/sandbox-macos-minimal.sb`) but allows other operations.
- `strict`: Uses a strict profile that declines operations by default.
- `<profile_name>`: Uses a custom profile. To define a custom profile, create a file named `sandbox-macos-<profile_name>.sb` in your project's `.gemini/` directory (e.g., `my-project/.gemini/sandbox-macos-custom.sb`).
- **`DEBUG` or `DEBUG_MODE`** (often used by underlying libraries or the CLI itself):
- Set to `true` or `1` to enable verbose debug logging, which can be helpful for troubleshooting.

2
docs/tools/index.md
View File

@ -33,7 +33,7 @@ You will typically see messages in the CLI indicating when a tool is being calle
Many tools, especially those that can modify your file system or execute commands (`write_file`, `edit`, `execute_bash_command`), are designed with safety in mind. The Gemini CLI will typically:
- **Require Confirmation:** Prompt you before executing potentially sensitive operations, showing you what action is about to be taken.
- **Utilize Sandboxing:** For tools like `execute_bash_command`, sandboxing mechanisms (configurable via settings) are employed to limit the potential impact of the command.
- **Utilize Sandboxing:** All tools are subject to restrictions enforced by sandboxing (see [README](../../README.md#sandboxing)).
It's important to always review confirmation prompts carefully before allowing a tool to proceed.

12
docs/troubleshooting.md
View File

@ -10,10 +10,10 @@ This guide provides solutions to common issues and debugging tips.
- **Q: Where are the CLI configuration files stored?**
- A: The CLI configuration is typically managed within `packages/cli/src/config/`. Refer to `docs/cli/configuration.md` for more details.
- A: The CLI configuration is typically managed within `packages/cli/src/config/`. Refer to [CLI Configuration](./cli/configuration.md) for more details.
- **Q: Where are the server configuration files stored?**
- A: The server configuration is typically managed within `packages/server/src/config/`. Refer to `docs/server/configuration.md` for more details.
- A: The server configuration is typically managed within `packages/server/src/config/`. Refer to [Server Configuration](./server/configuration.md) for more details.
## Common Error Messages and Solutions
@ -22,7 +22,7 @@ This guide provides solutions to common issues and debugging tips.
- **Cause:** Another process is already using the port the server is trying to bind to.
- **Solution:**
1. Stop the other process using the port.
2. Configure the server to use a different port (see `docs/server/configuration.md`).
2. Configure the server to use a different port (see [`server/configuration.md`](./server/configuration.md)).
- **Error: Command not found (when using the CLI).**
@ -39,9 +39,9 @@ This guide provides solutions to common issues and debugging tips.
1. Run `npm install` to ensure all dependencies are present.
2. Run `npm run build` to compile the project.
- **Error: MacOS Seatbelt "Operation not permitted" or similar.**
- **Cause:** The application is attempting an operation restricted by the MacOS Seatbelt profile it's running under. This is a security feature of MacOS.
- **Solution:** The specific Seatbelt profile (`sandbox-macos-minimal.sb` or `sandbox-macos-strict.sb` in `packages/cli/src/utils/`) may need to be adjusted to permit the required operation. This involves understanding the sandbox profile language and carefully considering the security implications of any changes. Modifying sandbox profiles can be complex and should be done with caution.
- **Error: "Operation not permitted" or "Permission denied" or similar.**
- **Cause:** If sandboxing is enabled, then the application is likely attempting an operation restricted by your sandbox, such as writing outside the project directory or system temp directory.
- **Solution:** See [README](../README.md#sandboxing) for more information on sandboxing, including how to customize your sandbox configuration.
## Debugging Tips