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 (only when keyring is disabled)
permissions/tool_permissions.json - Runtime permission decisions (auto-managed)

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_CLI_SHOW_COST`	Show estimated cost for token use in the CLI	true/false	false	No
`GOOSE_ALLOWLIST`	URL for allowed extensions	Valid URL	None	No
`GOOSE_RECIPE_GITHUB_REPO`	GitHub repository for recipes	Format: "org/repo"	None	No
`GOOSE_AUTO_COMPACT_THRESHOLD`	Set the percentage threshold at which goose automatically summarizes your session.	Float between 0.0 and 1.0 (disabled at 0.0)	0.8	No
`otel_exporter_otlp_endpoint`	OTLP endpoint URL for observability	URL (e.g., `http://localhost:4318`)	None	No
`otel_exporter_otlp_timeout`	Export timeout in milliseconds for observability	Integer (ms)	10000	No
`security_prompt_enabled`	Enable prompt injection detection to identify potentially harmful commands	true/false	false	No
`security_prompt_threshold`	Sensitivity threshold for prompt injection detection (higher = stricter)	Float between 0.01 and 1.0	0.7	No

Automatic Multi-Model Configuration

The experimental AutoPilot feature provides intelligent, context-aware model switching. Configure models for different roles using the x-advanced-models setting.

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 access to experimental alpha features—check the feature docs to see if this flag is required	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-4.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"

# Observability (OpenTelemetry)
otel_exporter_otlp_endpoint: "http://localhost:4318"
otel_exporter_otlp_timeout: 20000

# 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"/"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 config files 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.

Configuration Files​

Global Settings​

Experimental Features​

Example Configuration​

Extensions Configuration​

Configuration Priority​

Security Considerations​

Updating Configuration​

See Also​