mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-02-01 22:48:03 +00:00
docs(config): update documentation for settings structure (#7352)
This commit is contained in:
Gal Zahavi
@@ -25,8 +25,12 @@ Here is how settings from different levels are combined.
|
||||
|
||||
```json
|
||||
{
|
||||
"theme": "default-corporate-theme",
|
||||
"includeDirectories": ["/etc/gemini-cli/common-context"]
|
||||
"ui": {
|
||||
"theme": "default-corporate-theme"
|
||||
},
|
||||
"context": {
|
||||
"includeDirectories": ["/etc/gemini-cli/common-context"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -34,7 +38,9 @@ Here is how settings from different levels are combined.
|
||||
|
||||
```json
|
||||
{
|
||||
"theme": "user-preferred-dark-theme",
|
||||
"ui": {
|
||||
"theme": "user-preferred-dark-theme"
|
||||
},
|
||||
"mcpServers": {
|
||||
"corp-server": {
|
||||
"command": "/usr/local/bin/corp-server-dev"
|
||||
@@ -43,7 +49,9 @@ Here is how settings from different levels are combined.
|
||||
"command": "npm start --prefix ~/tools/my-tool"
|
||||
}
|
||||
},
|
||||
"includeDirectories": ["~/gemini-context"]
|
||||
"context": {
|
||||
"includeDirectories": ["~/gemini-context"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -51,26 +59,34 @@ Here is how settings from different levels are combined.
|
||||
|
||||
```json
|
||||
{
|
||||
"theme": "project-specific-light-theme",
|
||||
"ui": {
|
||||
"theme": "project-specific-light-theme"
|
||||
},
|
||||
"mcpServers": {
|
||||
"project-tool": {
|
||||
"command": "npm start"
|
||||
}
|
||||
},
|
||||
"includeDirectories": ["./project-context"]
|
||||
"context": {
|
||||
"includeDirectories": ["./project-context"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **System Overrides `settings.json`:**
|
||||
```json
|
||||
{
|
||||
"theme": "system-enforced-theme",
|
||||
"ui": {
|
||||
"theme": "system-enforced-theme"
|
||||
},
|
||||
"mcpServers": {
|
||||
"corp-server": {
|
||||
"command": "/usr/local/bin/corp-server-prod"
|
||||
}
|
||||
},
|
||||
"includeDirectories": ["/etc/gemini-cli/global-context"]
|
||||
"context": {
|
||||
"includeDirectories": ["/etc/gemini-cli/global-context"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -79,7 +95,9 @@ This results in the following merged configuration:
|
||||
- **Final Merged Configuration:**
|
||||
```json
|
||||
{
|
||||
"theme": "system-enforced-theme",
|
||||
"ui": {
|
||||
"theme": "system-enforced-theme"
|
||||
},
|
||||
"mcpServers": {
|
||||
"corp-server": {
|
||||
"command": "/usr/local/bin/corp-server-prod"
|
||||
@@ -91,12 +109,14 @@ This results in the following merged configuration:
|
||||
"command": "npm start"
|
||||
}
|
||||
},
|
||||
"includeDirectories": [
|
||||
"/etc/gemini-cli/common-context",
|
||||
"~/gemini-context",
|
||||
"./project-context",
|
||||
"/etc/gemini-cli/global-context"
|
||||
]
|
||||
"context": {
|
||||
"includeDirectories": [
|
||||
"/etc/gemini-cli/common-context",
|
||||
"~/gemini-context",
|
||||
"./project-context",
|
||||
"/etc/gemini-cli/global-context"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -117,7 +137,7 @@ By using the system settings file, you can enforce the security and configuratio
|
||||
|
||||
## Restricting Tool Access
|
||||
|
||||
You can significantly enhance security by controlling which tools the Gemini model can use. This is achieved through the `coreTools` and `excludeTools` settings. For a list of available tools, see the [Tools documentation](../tools/index.md).
|
||||
You can significantly enhance security by controlling which tools the Gemini model can use. This is achieved through the `tools.core` and `tools.exclude` settings. For a list of available tools, see the [Tools documentation](../tools/index.md).
|
||||
|
||||
### Allowlisting with `coreTools`
|
||||
|
||||
@@ -127,7 +147,9 @@ The most secure approach is to explicitly add the tools and commands that users
|
||||
|
||||
```json
|
||||
{
|
||||
"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
|
||||
"tools": {
|
||||
"core": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -139,7 +161,9 @@ Alternatively, you can add specific tools that are considered dangerous in your
|
||||
|
||||
```json
|
||||
{
|
||||
"excludeTools": ["ShellTool(rm -rf)"]
|
||||
"tools": {
|
||||
"exclude": ["ShellTool(rm -rf)"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -172,7 +196,9 @@ Following the principle of least privilege, it is highly recommended to use `inc
|
||||
|
||||
```json
|
||||
{
|
||||
"allowMCPServers": ["third-party-analyzer"],
|
||||
"mcp": {
|
||||
"allowed": ["third-party-analyzer"]
|
||||
},
|
||||
"mcpServers": {
|
||||
"third-party-analyzer": {
|
||||
"command": "/usr/local/bin/start-3p-analyzer.sh",
|
||||
@@ -187,7 +213,7 @@ Following the principle of least privilege, it is highly recommended to use `inc
|
||||
To create a secure, centrally-managed catalog of tools, the system administrator **must** do both of the following in the system-level `settings.json` file:
|
||||
|
||||
1. **Define the full configuration** for every approved server in the `mcpServers` object. This ensures that even if a user defines a server with the same name, the secure system-level definition will take precedence.
|
||||
2. **Add the names** of those servers to an allowlist using the `allowMCPServers` setting. This is a critical security step that prevents users from running any servers that are not on this list. If this setting is omitted, the CLI will merge and allow any server defined by the user.
|
||||
2. **Add the names** of those servers to an allowlist using the `mcp.allowed` setting. This is a critical security step that prevents users from running any servers that are not on this list. If this setting is omitted, the CLI will merge and allow any server defined by the user.
|
||||
|
||||
**Example System `settings.json`:**
|
||||
|
||||
@@ -198,7 +224,9 @@ To create a secure, centrally-managed catalog of tools, the system administrator
|
||||
|
||||
```json
|
||||
{
|
||||
"allowMCPServers": ["corp-data-api", "source-code-analyzer"],
|
||||
"mcp": {
|
||||
"allowed": ["corp-data-api", "source-code-analyzer"]
|
||||
},
|
||||
"mcpServers": {
|
||||
"corp-data-api": {
|
||||
"command": "/usr/local/bin/start-corp-api.sh",
|
||||
@@ -211,16 +239,16 @@ To create a secure, centrally-managed catalog of tools, the system administrator
|
||||
}
|
||||
```
|
||||
|
||||
This pattern is more secure because it uses both definition and an allowlist. Any server a user defines will either be overridden by the system definition (if it has the same name) or blocked because its name is not in the `allowMCPServers` list.
|
||||
This pattern is more secure because it uses both definition and an allowlist. Any server a user defines will either be overridden by the system definition (if it has the same name) or blocked because its name is not in the `mcp.allowed` list.
|
||||
|
||||
### Less Secure Pattern: Omitting the Allowlist
|
||||
|
||||
If the administrator defines the `mcpServers` object but fails to also specify the `allowMCPServers` allowlist, users may add their own servers.
|
||||
If the administrator defines the `mcpServers` object but fails to also specify the `mcp.allowed` allowlist, users may add their own servers.
|
||||
|
||||
**Example System `settings.json`:**
|
||||
|
||||
This configuration defines servers but does not enforce the allowlist.
|
||||
The administrator has NOT included the "allowMCPServers" setting.
|
||||
The administrator has NOT included the "mcp.allowed" setting.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -232,7 +260,7 @@ The administrator has NOT included the "allowMCPServers" setting.
|
||||
}
|
||||
```
|
||||
|
||||
In this scenario, a user can add their own server in their local `settings.json`. Because there is no `allowMCPServers` list to filter the merged results, the user's server will be added to the list of available tools and allowed to run.
|
||||
In this scenario, a user can add their own server in their local `settings.json`. Because there is no `mcp.allowed` list to filter the merged results, the user's server will be added to the list of available tools and allowed to run.
|
||||
|
||||
## Enforcing Sandboxing for Security
|
||||
|
||||
@@ -242,7 +270,9 @@ To mitigate the risk of potentially harmful operations, you can enforce the use
|
||||
|
||||
```json
|
||||
{
|
||||
"sandbox": "docker"
|
||||
"tools": {
|
||||
"sandbox": "docker"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -293,36 +323,39 @@ Here is an example of a system `settings.json` file that combines several of the
|
||||
|
||||
```json
|
||||
{
|
||||
"sandbox": "docker",
|
||||
|
||||
"coreTools": [
|
||||
"ReadFileTool",
|
||||
"GlobTool",
|
||||
"ShellTool(ls)",
|
||||
"ShellTool(cat)",
|
||||
"ShellTool(grep)"
|
||||
],
|
||||
|
||||
"tools": {
|
||||
"sandbox": "docker",
|
||||
"core": [
|
||||
"ReadFileTool",
|
||||
"GlobTool",
|
||||
"ShellTool(ls)",
|
||||
"ShellTool(cat)",
|
||||
"ShellTool(grep)"
|
||||
]
|
||||
},
|
||||
"mcp": {
|
||||
"allowed": ["corp-tools"]
|
||||
},
|
||||
"mcpServers": {
|
||||
"corp-tools": {
|
||||
"command": "/opt/gemini-tools/start.sh",
|
||||
"timeout": 5000
|
||||
}
|
||||
},
|
||||
"allowMCPServers": ["corp-tools"],
|
||||
|
||||
"telemetry": {
|
||||
"enabled": true,
|
||||
"target": "gcp",
|
||||
"otlpEndpoint": "https://telemetry-prod.example.com:4317",
|
||||
"logPrompts": false
|
||||
},
|
||||
|
||||
"bugCommand": {
|
||||
"urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
|
||||
"advanced": {
|
||||
"bugCommand": {
|
||||
"urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
|
||||
}
|
||||
},
|
||||
|
||||
"usageStatisticsEnabled": false
|
||||
"privacy": {
|
||||
"usageStatisticsEnabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user