Configuration Overview

goose uses YAML 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 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, 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 (when goose is using file-based secret storage)
• permissions/tool_permissions.json - Runtime permission decisions (auto-managed)
• prompts/ - Customized prompt templates

In addition to editing configuration files directly, many settings can be managed from goose Desktop and goose CLI:

• goose Desktop: From the Settings page and the bottom toolbar
• goose CLI: Run the goose configure command

Provider Configuration

Provider settings are stored in the active_provider and providers keys:

active_provider: anthropic
providers:
  anthropic:
    enabled: true
    model: claude-sonnet-4-5-20250929
    configured: true

GOOSE_PROVIDER and GOOSE_MODEL are still supported as environment variables and override the config file for that process. Older config files that use flat GOOSE_PROVIDER and GOOSE_MODEL keys are read for compatibility and migrated when goose updates the provider settings.

Global Settings

The following settings can be configured at the root level of your config.yaml file:

Additional environment variables may also be supported in config.yaml.

Example Configuration

Here's a basic example of a config.yaml file:

# Model Configuration
active_provider: anthropic
providers:
  anthropic:
    enabled: true
    model: claude-sonnet-4-5-20250929
    configured: true
GOOSE_TEMPERATURE: 0.7

# Planning Configuration
GOOSE_PLANNER_PROVIDER: "openai"
GOOSE_PLANNER_MODEL: "gpt-4"

# Tool Configuration
GOOSE_MODE: "smart_approve"
GOOSE_TOOLSHIM: true
GOOSE_CLI_MIN_PRIORITY: 0.2

# Recipe Configuration
GOOSE_RECIPE_GITHUB_REPO: "aaif-goose/goose-recipes"

# Search Path Configuration
GOOSE_SEARCH_PATHS:
  - "/usr/local/bin"
  - "~/custom/tools"
  - "/opt/homebrew/bin"

# Security Configuration
SECURITY_PROMPT_ENABLED: true

# Extensions Configuration
extensions:
  developer:
    bundled: true
    enabled: true
    name: developer
    timeout: 300
    type: builtin
  
  memory:
    bundled: true
    enabled: true
    name: memory
    timeout: 300
    type: builtin

Extensions Configuration

Extensions are configured under the extensions key. Each extension can have the following settings:

extensions:
  extension_name:
    bundled: true/false       # Whether it's included with goose
    display_name: "Name"      # Human-readable name (optional)
    enabled: true/false       # Whether the extension is active
    name: "extension_name"    # Internal name
    timeout: 300              # Operation timeout in seconds
    type: "builtin"           # Extension type
    available_tools: []       # Filter to specific tools (empty = all)

Supported extension types are builtin, platform, stdio, streamable_http, frontend, and inline_python. sse may appear in older configs, but is kept only for compatibility.

Common extension shapes:

extensions:
  developer:
    type: builtin
    name: developer
    enabled: true
    bundled: true
    timeout: 300

  computercontroller:
    type: platform
    name: computercontroller
    display_name: Computer Controller
    enabled: true
    bundled: true

  filesystem:
    type: stdio
    name: filesystem
    enabled: true
    cmd: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    env_keys: []
    envs: {}
    timeout: 300

  remote-tools:
    type: streamable_http
    name: remote-tools
    enabled: true
    uri: "https://example.com/mcp"
    headers: {}
    env_keys: []
    envs: {}
    timeout: 300

Tool Filtering

Use the available_tools field to limit which tools are loaded from an extension. List the tool names you want — only those will be available to goose. Leave it empty (the default) to load all tools. This can help reduce token overhead in sessions where you only need a subset of an extension's capabilities.

Search Path Configuration

Extensions may need to execute external commands or tools. Goose builds the command search path from any GOOSE_SEARCH_PATHS entries, built-in fallback paths, and then your system PATH. You can add additional search directories in your config file:

GOOSE_SEARCH_PATHS:
  - "/usr/local/bin"
  - "~/custom/tools"
  - "/opt/homebrew/bin"

These paths are checked before the built-in fallback paths and system PATH when running extension commands, ensuring your custom tools are found without modifying your global PATH.

Observability Configuration

Configure goose to export telemetry to OpenTelemetry compatible platforms. Environment variables override these settings and support additional options like per-signal configuration. See the environment variables guide for details.

otel_exporter_otlp_endpoint: "http://localhost:4318"
otel_exporter_otlp_timeout: 20000

Recipe Command Configuration

You can optionally set up custom slash commands to run recipes that you create. List the command (without the leading /) along with the path to the recipe:

slash_commands:
  - command: "run-tests"
    recipe_path: "/path/to/recipe.yaml"
  - command: "daily-standup"
    recipe_path: "/Users/me/.local/share/goose/recipes/standup.yaml"

Configuration Priority

Settings are applied in the following order of precedence:

1. Environment variables (highest priority)
2. Config file settings
3. Default values (lowest priority)

Security Considerations

:::warning Provider API keys do not go in config.yaml goose does not read provider API keys from config.yaml. A key placed there is ignored, which typically surfaces as an authentication failure such as No api key passed in. Store the key in the system keyring (via goose configure), or—when using file-based secret storage—in secrets.yaml. It can also be supplied through the provider's environment variable (for example OPENAI_API_KEY), which takes precedence over stored secrets. :::

• Avoid storing sensitive information (API keys, tokens) in the config file

• Use the system keyring (keychain on macOS) for storing secrets. When available, this is the recommended option.

• If goose is using file-based secret storage, secrets are stored in a separate secrets.yaml file (in plain text). This can happen when:

  • Your environment does not provide a desktop keyring service (for example: headless servers, CI/CD, containers)
  • You disable the keyring explicitly (via GOOSE_DISABLE_KEYRING)
  • goose cannot access the keyring and falls back to file-based secret storage

  For troubleshooting keyring failures and automatic fallback behavior, see Known Issues.

Updating Configuration

Direct edits to config files usually require restarting goose to take effect for existing sessions. Goose2 provider credential/config saves made through Settings use ACP/core to update storage and refresh provider inventory without restarting the app, but currently active chat sessions continue using the provider instance they started with. You can verify your current configuration using:

goose info -v

This will show all active settings and their current values.

See Also

• Multi-Model Configuration - For multiple model-selection strategies
• Environment Variables - For environment variable configuration
• Using Extensions - For more details on extension configuration