Configuration File

Goose uses a YAML configuration file to manage settings and extensions. This 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, the config file provides a persistent way to maintain your preferences.

Global Settings

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

Setting	Purpose	Values	Default	Required
`GOOSE_PROVIDER`	Primary LLM provider	"anthropic", "openai", etc.	None	Yes
`GOOSE_MODEL`	Default model to use	Model name (e.g., "claude-3.5-sonnet", "gpt-4")	None	Yes
`GOOSE_TEMPERATURE`	Model response randomness	Float between 0.0 and 1.0	Model-specific	No
`GOOSE_MODE`	Tool execution behavior	"auto", "approve", "chat", "smart_approve"	"smart_approve"	No
`GOOSE_MAX_TURNS`	Maximum number of turns allowed without user input	Integer (e.g., 10, 50, 100)	1000	No
`GOOSE_LEAD_PROVIDER`	Provider for lead model in lead/worker mode	Same as `GOOSE_PROVIDER` options	Falls back to `GOOSE_PROVIDER`	No
`GOOSE_LEAD_MODEL`	Lead model for lead/worker mode	Model name	None	No
`GOOSE_PLANNER_PROVIDER`	Provider for planning mode	Same as `GOOSE_PROVIDER` options	Falls back to `GOOSE_PROVIDER`	No
`GOOSE_PLANNER_MODEL`	Model for planning mode	Model name	Falls back to `GOOSE_MODEL`	No
`GOOSE_TOOLSHIM`	Enable tool interpretation	true/false	false	No
`GOOSE_TOOLSHIM_OLLAMA_MODEL`	Model for tool interpretation	Model name (e.g., "llama3.2")	System default	No
`GOOSE_CLI_MIN_PRIORITY`	Tool output verbosity	Float between 0.0 and 1.0	0.0	No
`GOOSE_CLI_THEME`	Theme for CLI response markdown	"light", "dark", "ansi"	"dark"	No
`GOOSE_ALLOWLIST`	URL for allowed extensions	Valid URL	None	No
`GOOSE_RECIPE_GITHUB_REPO`	GitHub repository for recipes	Format: "org/repo"	None	No

Experimental Features

These settings enable experimental features that are in active development. These may change or be removed in future releases.

Setting	Purpose	Values	Default	Required
`ALPHA_FEATURES`	Enables experimental alpha features like subagents	true/false	false	No

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

Example Configuration

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

# Model Configuration
GOOSE_PROVIDER: "anthropic"
GOOSE_MODEL: "claude-3.5-sonnet"
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: "block/goose-recipes"

# Experimental Features
ALPHA_FEATURES: 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"/"stdio"   # Extension type
    
    # Additional settings for stdio extensions:
    cmd: "command"            # Command to execute
    args: ["arg1", "arg2"]    # Command arguments
    description: "text"       # Extension description
    env_keys: []             # Required environment variables
    envs: {}                 # Environment values

Configuration Priority

Settings are applied in the following order of precedence:

Environment variables (highest priority)
Config file settings
Default values (lowest priority)

Security Considerations

Avoid storing sensitive information (API keys, tokens) in the config file
Use the system keyring for storing secrets
If keyring is disabled, secrets are stored in a separate secrets.yaml file

Updating Configuration

Changes to the config file require restarting Goose to take effect. You can verify your current configuration using:

goose info -v

This will show all active settings and their current values.

Global Settings​

Experimental Features​

Example Configuration​

Extensions Configuration​

Configuration Priority​

Security Considerations​

Updating Configuration​

See Also​