From 40f453445f28eb12740cb1c1b1e9613bdf8a2dd9 Mon Sep 17 00:00:00 2001 From: "Anthony D. Mays" Date: Wed, 29 Oct 2025 13:46:01 -0700 Subject: [PATCH] docs: clarifies config file locations and purposes (#5210) Signed-off-by: Anthony D. Mays --- BUILDING_DOCKER.md | 2 +- .../docs/getting-started/installation.md | 5 +++-- .../docs/getting-started/using-extensions.md | 2 +- documentation/docs/guides/acp-clients.md | 2 +- .../{config-file.md => config-files.md} | 19 +++++++++++++------ .../docs/guides/environment-variables.md | 2 +- .../docs/guides/goose-cli-commands.md | 2 +- .../docs/guides/managing-tools/tool-router.md | 2 +- .../docs/guides/multi-model/autopilot.md | 2 +- .../docs/guides/recipes/session-recipes.md | 2 +- .../security/prompt-injection-detection.md | 2 +- .../sessions/smart-context-management.md | 4 ++-- documentation/docs/guides/subagents.mdx | 2 +- documentation/docs/troubleshooting.md | 2 +- documentation/docusaurus.config.ts | 4 ++++ 15 files changed, 33 insertions(+), 21 deletions(-) rename documentation/docs/guides/{config-file.md => config-files.md} (87%) diff --git a/BUILDING_DOCKER.md b/BUILDING_DOCKER.md index ef3b62e0..ed61e4b5 100644 --- a/BUILDING_DOCKER.md +++ b/BUILDING_DOCKER.md @@ -319,4 +319,4 @@ When contributing Docker-related changes: - [goose in Docker Tutorial](documentation/docs/tutorials/goose-in-docker.md) - Step-by-step tutorial - [Installation Guide](https://block.github.io/goose/docs/getting-started/installation) - All installation methods -- [Configuration Guide](https://block.github.io/goose/docs/guides/config-file) - Detailed configuration options +- [Configuration Guide](https://block.github.io/goose/docs/guides/config-files) - Detailed configuration options diff --git a/documentation/docs/getting-started/installation.md b/documentation/docs/getting-started/installation.md index c7bb4269..93392be7 100644 --- a/documentation/docs/getting-started/installation.md +++ b/documentation/docs/getting-started/installation.md @@ -376,10 +376,10 @@ You can change your LLM provider and/or model or update your API key at any time ## Shared Configuration Settings -The Goose CLI and Desktop UI share all core configurations, including LLM provider settings, model selection, and extension configurations. When you install or configure extensions in either interface, the settings are stored in a central location at `~/.config/goose/config.yaml`, making them available to both the Desktop application and CLI. This makes it convenient to switch between interfaces while maintaining consistent settings. +The Goose CLI and Desktop UI share all core configurations, including LLM provider settings, model selection, and extension configurations. When you install or configure extensions in either interface, the settings are stored in a central location, making them available to both the Desktop application and CLI. This makes it convenient to switch between interfaces while maintaining consistent settings. For more information, visit the [Config Files][config-files] guide. :::info -While core configurations are shared between interfaces, extensions have flexibility in how they store authentication credentials. Some extensions may use the shared config file while others implement their own storage methods. +While core configurations are shared between interfaces, extensions have flexibility in how they store authentication credentials. Some extensions may use the shared config files while others implement their own storage methods. ::: @@ -404,3 +404,4 @@ You can also configure Extensions to extend Goose's functionality, including add [providers]: /docs/getting-started/providers [handling-rate-limits]: /docs/guides/handling-llm-rate-limits-with-goose [mcp]: https://www.anthropic.com/news/model-context-protocol +[config-files]: /docs/guides/config-files.md diff --git a/documentation/docs/getting-started/using-extensions.md b/documentation/docs/getting-started/using-extensions.md index ced2fdd7..763f6193 100644 --- a/documentation/docs/getting-started/using-extensions.md +++ b/documentation/docs/getting-started/using-extensions.md @@ -523,7 +523,7 @@ Goose relies on extension properties to determine how to handle an extension. Yo - 1. Navigate to the Goose [configuration file](/docs/guides/config-file). For example, navigate to `~/.config/goose/config.yaml` on macOS. + 1. Navigate to the Goose [configuration file](/docs/guides/config-files). For example, navigate to `~/.config/goose/config.yaml` on macOS. 2. Edit the extension properties as needed and save your changes. diff --git a/documentation/docs/guides/acp-clients.md b/documentation/docs/guides/acp-clients.md index 0f072d9e..815d0dc0 100644 --- a/documentation/docs/guides/acp-clients.md +++ b/documentation/docs/guides/acp-clients.md @@ -77,7 +77,7 @@ You should now be able to interact with Goose directly in Zed. Your ACP sessions ### Advanced Configuration -By default, Goose will use the provider and model defined in your [configuration file](/docs/guides/config-file). You can override this for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables. +By default, Goose will use the provider and model defined in your [configuration file](/docs/guides/config-files). You can override this for specific ACP configurations using the `GOOSE_PROVIDER` and `GOOSE_MODEL` environment variables. The following Zed settings example configures two Goose agent instances. This is useful for: - Comparing model performance on the same task diff --git a/documentation/docs/guides/config-file.md b/documentation/docs/guides/config-files.md similarity index 87% rename from documentation/docs/guides/config-file.md rename to documentation/docs/guides/config-files.md index 73ebb688..8a475473 100644 --- a/documentation/docs/guides/config-file.md +++ b/documentation/docs/guides/config-files.md @@ -1,17 +1,24 @@ --- sidebar_position: 85 -title: Configuration File -sidebar_label: Configuration File +title: Configuration Files +sidebar_label: Configuration Files --- -# Configuration File +# Configuration Overview -goose uses a YAML configuration file to manage settings and extensions. This file is located at: +goose uses YAML [configuration files](#configuration-files) to manage settings and extensions. The primary config file is located at: * macOS/Linux: `~/.config/goose/config.yaml` * Windows: `%APPDATA%\Block\goose\config\config.yaml` -The configuration file allows you to set default behaviors, configure language models, and manage extensions. While many settings can also be set using [environment variables](/docs/guides/environment-variables), the config file provides a persistent way to maintain your preferences. +The configuration files allow you to set default behaviors, configure language models, set tool permissions, and manage extensions. While many settings can also be set using [environment variables](/docs/guides/environment-variables), the config files provide a persistent way to maintain your preferences. + +## Configuration Files + +- **config.yaml** - Provider, model, extensions, and general settings +- **permission.yaml** - Tool permission levels configured via `goose configure` +- **secrets.yaml** - API keys and secrets (only when keyring is disabled) +- **permissions/tool_permissions.json** - Runtime permission decisions (auto-managed) ## Global Settings @@ -139,7 +146,7 @@ Settings are applied in the following order of precedence: ## Updating Configuration -Changes to the config file require restarting goose to take effect. You can verify your current configuration using: +Changes to config files require restarting goose to take effect. You can verify your current configuration using: ```bash goose info -v diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index 7f6dc0f2..40c5b02d 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -70,7 +70,7 @@ A _turn_ is one complete prompt-response interaction. Here's how it works with t - Fallback to the lead model if the worker model struggles for 2 consecutive turns - Use the lead model for 2 turns and then switch back to the worker model -The lead model and worker model names are displayed at the start of the goose CLI session. If you don't export a `GOOSE_MODEL` for your session, the worker model defaults to the `GOOSE_MODEL` in your [configuration file](/docs/guides/config-file). +The lead model and worker model names are displayed at the start of the goose CLI session. If you don't export a `GOOSE_MODEL` for your session, the worker model defaults to the `GOOSE_MODEL` in your [configuration file](/docs/guides/config-files). **Examples** diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index aa9ed002..e137fdc9 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -507,7 +507,7 @@ The `/t` command controls the syntax highlighting theme for markdown content in **Configuration:** - The default theme is `dark` -- The theme setting is saved to the [configuration file](/docs/guides/config-file) as `GOOSE_CLI_THEME` and persists between sessions +- The theme setting is saved to the [configuration file](/docs/guides/config-files) as `GOOSE_CLI_THEME` and persists between sessions - The saved configuration can be overridden for the session using the `GOOSE_CLI_THEME` [environment variable](/docs/guides/environment-variables#session-management) :::info diff --git a/documentation/docs/guides/managing-tools/tool-router.md b/documentation/docs/guides/managing-tools/tool-router.md index 12e737d3..65bc1730 100644 --- a/documentation/docs/guides/managing-tools/tool-router.md +++ b/documentation/docs/guides/managing-tools/tool-router.md @@ -147,7 +147,7 @@ When enabled, Goose uses LLM intelligence to analyze your query and select only ## Environment Variable Configuration -You can also configure tool selection using environment variables or in your [configuration file](/docs/guides/config-file): +You can also configure tool selection using environment variables or in your [configuration file](/docs/guides/config-files): ```bash # Enable LLM-based tool selection diff --git a/documentation/docs/guides/multi-model/autopilot.md b/documentation/docs/guides/multi-model/autopilot.md index 888e4645..ef302b32 100644 --- a/documentation/docs/guides/multi-model/autopilot.md +++ b/documentation/docs/guides/multi-model/autopilot.md @@ -33,7 +33,7 @@ You can use `goose session --debug` in goose CLI to see when AutoPilot switches ## Configuration -Add the `x-advanced-models` section to your [`config.yaml`](/docs/guides/config-file) file and map your model preferences to [predefined](#predefined-roles) or custom roles. +Add the `x-advanced-models` section to your [`config.yaml`](/docs/guides/config-files) file and map your model preferences to [predefined](#predefined-roles) or custom roles. The `provider`, `model` and `role` parameters are required. diff --git a/documentation/docs/guides/recipes/session-recipes.md b/documentation/docs/guides/recipes/session-recipes.md index 9f369cc1..1b48459a 100644 --- a/documentation/docs/guides/recipes/session-recipes.md +++ b/documentation/docs/guides/recipes/session-recipes.md @@ -265,7 +265,7 @@ You can turn your current goose session into a reusable recipe that includes the #### Configure Recipe Location - Recipes can be stored locally on your device or in a GitHub repository. Configure your recipe repository using either the `goose configure` command or [config file](/docs/guides/config-file#global-settings). + Recipes can be stored locally on your device or in a GitHub repository. Configure your recipe repository using either the `goose configure` command or [config file](/docs/guides/config-files#global-settings). :::tip Repository Structure - Each recipe should be in its own directory diff --git a/documentation/docs/guides/security/prompt-injection-detection.md b/documentation/docs/guides/security/prompt-injection-detection.md index 2afe6d91..9d82f578 100644 --- a/documentation/docs/guides/security/prompt-injection-detection.md +++ b/documentation/docs/guides/security/prompt-injection-detection.md @@ -64,7 +64,7 @@ When in doubt, deny. - Add these settings to your [`config.yaml`](/docs/guides/config-file): + Add these settings to your [`config.yaml`](/docs/guides/config-files): ```yaml security_prompt_enabled: true diff --git a/documentation/docs/guides/sessions/smart-context-management.md b/documentation/docs/guides/sessions/smart-context-management.md index ff67cf79..6b5f4baa 100644 --- a/documentation/docs/guides/sessions/smart-context-management.md +++ b/documentation/docs/guides/sessions/smart-context-management.md @@ -159,7 +159,7 @@ This feature gives you control over agent autonomy and prevents infinite loops a - Enabling human supervision or interaction during autonomous operations - Controlling loops while testing and debugging agent behavior -This setting is stored as the `GOOSE_MAX_TURNS` environment variable in your [config.yaml file](/docs/guides/config-file). You can configure it using the Desktop app or CLI. +This setting is stored as the `GOOSE_MAX_TURNS` environment variable in your [config.yaml file](/docs/guides/config-files). You can configure it using the Desktop app or CLI. @@ -375,7 +375,7 @@ Pricing data is regularly fetched from the OpenRouter API and cached locally. Th These costs are estimates only, and not connected to your actual provider bill. The cost shown is an approximation based on token counts and public pricing data. - Show estimated cost in the Goose CLI by setting the `GOOSE_CLI_SHOW_COST` [environment variable](/docs/guides/environment-variables.md#session-management) or including it in the [configuration file](/docs/guides/config-file.md). + Show estimated cost in the Goose CLI by setting the `GOOSE_CLI_SHOW_COST` [environment variable](/docs/guides/environment-variables.md#session-management) or including it in the [configuration file](/docs/guides/config-files.md). ``` # Set environment variable diff --git a/documentation/docs/guides/subagents.mdx b/documentation/docs/guides/subagents.mdx index c2dd4cc8..776a5123 100644 --- a/documentation/docs/guides/subagents.mdx +++ b/documentation/docs/guides/subagents.mdx @@ -150,7 +150,7 @@ I'll use your code-reviewer recipe to create a specialized subagent for this ana External subagents let you bring in AI agents from other providers and platforms, enabling Goose to coordinate and integrate your workflow with the broader ecosystem. In the below example, we use Codex as a subagent by running it as an MCP server: -**[Goose Configuration File](/docs/guides/config-file)** (`.~/.config/goose/config.yaml `): +**[Goose Configuration File](/docs/guides/config-files)** (`.~/.config/goose/config.yaml `): ```yaml subagent: args: diff --git a/documentation/docs/troubleshooting.md b/documentation/docs/troubleshooting.md index 104b0e2d..65452b81 100644 --- a/documentation/docs/troubleshooting.md +++ b/documentation/docs/troubleshooting.md @@ -125,7 +125,7 @@ Failed to authenticate: Execution error: OAuth configuration not supported by th ``` To resolve: -1. Temporarily comment out or remove lead/worker model variables from your config file (`~/.config/goose/config.yaml`): +1. Temporarily comment out or remove lead/worker model variables from the main config file (`~/.config/goose/config.yaml`): ```yaml # GOOSE_LEAD_MODEL: your-model # GOOSE_WORKER_MODEL: your-model diff --git a/documentation/docusaurus.config.ts b/documentation/docusaurus.config.ts index 84384519..a550acf1 100644 --- a/documentation/docusaurus.config.ts +++ b/documentation/docusaurus.config.ts @@ -162,6 +162,10 @@ const config: Config = { from: '/docs/guides/creating-plans', to: '/docs/guides/multi-model/creating-plans' }, + { + from: '/docs/guides/config-file', + to: '/docs/guides/config-files', + }, // MCP tutorial redirects - moved from /docs/tutorials/ to /docs/mcp/ { from: '/docs/tutorials/agentql-mcp',