Skip to main content
Goose requires configuration before first use. At minimum, you need to select and configure an LLM provider.

​
Interactive Configuration

​
First-Time Setup

Run the configuration command: 
goose configure
This launches an interactive wizard that guides you through:
  1. Provider Selection: Choose from 30+ LLM providers
  2. Authentication: Enter API keys or complete OAuth flows
  3. Extension Setup (optional): Add MCP servers for extended capabilities
  4. Preferences (optional): Set telemetry, permissions, and output preferences
The configuration wizard automatically validates your credentials by making a test API call to ensure everything is working.

​
Modifying Configuration

Run goose configure again to modify settings: 
goose configure
The wizard will show your current configuration and allow you to:
  • Switch providers or models
  • Update API credentials
  • Add/remove extensions
  • Change preferences

​
Provider Configuration

​
Cloud Providers

For cloud-based LLM providers, you’ll typically need an API key.
Required Environment Variable:
export OPENAI_API_KEY="sk-..."
Optional Configuration:
export OPENAI_HOST="https://api.openai.com/v1"  # Custom endpoint
export OPENAI_ORGANIZATION="org-..."             # Organization ID
export OPENAI_PROJECT="proj_..."                 # Project ID
Available Models:
  • gpt-4.6 (latest)
  • gpt-4.5-preview
  • gpt-4o (default)
  • o1-preview, o1-mini
  • gpt-3.5-turbo
See the Providers overview for a complete list of supported providers and their configuration options.

​
Local Inference

For local models using Ollama: 
export GOOSE_PROVIDER="ollama"
# Optional: if Ollama is running on a different host
export OLLAMA_HOST="http://localhost:11434"
Then pull a model: 
ollama pull qwen3.2
Goose will automatically detect available models. Learn more in the Local Inference guide.

​
Configuration Files

Goose stores configuration in several locations:

​
Config Directory

~/.config/goose/
├── config.yaml          # Provider and extension configuration
└── .goosehints          # Project-specific hints

​
config.yaml Structure

provider: "anthropic"
model: "claude-4.5-sonnet"

extensions:
  - name: "filesystem"
    enabled: true
    transport:
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "./"]
  
  - name: "postgres"
    enabled: false
    transport:
      type: "stdio"
      command: "uvx"
      args: ["mcp-server-postgres", "postgresql://localhost/mydb"]
    env:
      DATABASE_URL: "postgresql://localhost/mydb"

preferences:
  telemetry: true
  auto_update: true
  permission_mode: "prompt"  # prompt, allow, deny
Do not store API keys or secrets in config.yaml. Use environment variables or the secure keyring storage instead.

​
Secret Storage

Goose stores sensitive credentials securely:
  • macOS: Keychain
  • Linux: Secret Service (GNOME Keyring, KWallet) or encrypted file
  • Windows: Credential Manager
Credentials are set during goose configure and never stored in plain text configuration files.

​
Environment Variables

Environment variables override configuration file values and are useful for:
  • Testing different providers
  • CI/CD environments
  • Temporary configuration changes

​
Common Variables

# Provider selection
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-4o"

# API credentials (provider-specific)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Goose behavior
export GOOSE_INPUT_LIMIT="32000"     # Max tokens for context
export GOOSE_PATH_ROOT="/tmp/goose" # Isolate data for testing

# Telemetry
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
See the Environment Variables guide for a complete reference.

​
Configuration Precedence

When multiple configuration sources exist, goose follows this precedence order (highest to lowest):
  1. Environment variables (GOOSE_*, provider-specific)
  2. Command-line flags (--provider, --model)
  3. Recipe parameters (when running a recipe)
  4. User config file (~/.config/goose/config.yaml)
  5. Project hints (.goosehints in working directory)
  6. Default values
This allows you to override configuration temporarily without modifying files.

​
Extension Configuration

​
Adding Extensions

During goose configure, you can add MCP servers: 
goose configure
# Select "Extensions" > "Add extension"
Or manually edit config.yaml: 
extensions:
  - name: "my-custom-tool"
    enabled: true
    transport:
      type: "stdio"
      command: "python"
      args: ["-m", "my_mcp_server"]
    env:
      API_KEY: "${MY_API_KEY}"  # Environment variable substitution

​
Extension Security

For security, goose:
  • Validates extension manifests
  • Prompts for tool execution (unless permission mode is set to “allow”)
  • Filters environment variables passed to extensions
  • Scans extension outputs for malware patterns
See the MCP Integration guide for detailed extension configuration.

​
Testing Your Configuration

After configuration, test that everything works: 
goose session
In the session, try a simple request: 
goose: What can I help you with?
you: Write a hello world program in Python
If the agent responds and can execute code, your configuration is working correctly.

​
Next Steps

CLI Usage

Learn how to use the goose command-line interface

Desktop App

Explore the graphical desktop application

Environment Variables

Complete reference for environment variable configuration

Extensions

Add custom tools and capabilities to goose

​
Troubleshooting

Check that:
  1. Your API key is correct and not expired
  2. The environment variable name matches the provider’s expectation
  3. Your account has API access enabled
  4. Your network allows connections to the provider’s API
Run goose configure again to re-enter credentials.
Verify that:
  1. The extension command is in your PATH
  2. Required dependencies are installed (e.g., npx for Node.js servers)
  3. The transport configuration matches the extension’s requirements
  4. Check logs with goose session --log-level debug
Remember the precedence order - environment variables override config files. Try:
  1. Unset conflicting environment variables: unset GOOSE_PROVIDER
  2. Delete and recreate the config: rm ~/.config/goose/config.yaml && goose configure
  3. Check for project-level .goosehints that might override settings
For more help, see the Troubleshooting guide or ask in our Discord community.

Build docs developers (and LLMs) love

Get started for freeTalk to us