vrr/goose

mirror of https://github.com/block/goose.git synced 2026-04-28 11:39:43 +00:00

docs: remove ALPHA_FEATURES flag from documentation (#7315 )

2026-02-18 20:14:12 +00:00

9.6 KiB

Raw Blame History

sidebar_position	title	sidebar_label
85	Configuration Files	Configuration Files

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

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_MAX_TOKENS`	Maximum number of tokens for each model response (truncates longer responses)	Positive integer	Model-specific	No
`GOOSE_MODE`	Tool execution behavior	"auto", "approve", "chat", "smart_approve"	"auto"	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
`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.8	No
`SECURITY_PROMPT_CLASSIFIER_ENABLED`	Enable ML-based prompt injection detection for advanced threat identification	true/false	false	No
`SECURITY_PROMPT_CLASSIFIER_ENDPOINT`	Classification endpoint URL for ML-based prompt injection detection	URL (e.g., "https://api.example.com/classify")	None	No
`SECURITY_PROMPT_CLASSIFIER_TOKEN`	Authentication token for `SECURITY_PROMPT_CLASSIFIER_ENDPOINT`	String	None	No
`GOOSE_TELEMETRY_ENABLED`	Enable anonymous usage data collection	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"

# 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"/"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

Search Path Configuration

Extensions may need to execute external commands or tools. By default, goose uses your system's PATH environment variable. You can add additional search directories in your config file:

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

These paths are prepended to the 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.

Setting	Purpose	Values	Default
`otel_exporter_otlp_endpoint`	OTLP endpoint URL	URL (e.g., `http://localhost:4318`)	None
`otel_exporter_otlp_timeout`	Export timeout in milliseconds	Integer (ms)	10000

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:

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 (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

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.

9.6 KiB Raw Blame History