Configuration

Configure goose with your LLM provider, extensions, and preferences

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.

OpenAI

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

Anthropic

Required Environment Variable:

export ANTHROPIC_API_KEY="sk-ant-..."

Optional Configuration:

export ANTHROPIC_HOST="https://api.anthropic.com"  # Custom endpoint

Available Models:

• claude-4.6-sonnet (latest)
• claude-4.5-sonnet (default)
• claude-4.0-opus
• claude-3-haiku

Databricks

Databricks supports both token and OAuth authentication.

Token Authentication:

export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="dapi..."

OAuth Authentication:

export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
# Run goose configure to complete OAuth flow

Models are automatically discovered from your workspace.

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

macOS/Linux

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

Windows

%APPDATA%\goose\
├── config.yaml
└── .goosehints

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

Provider authentication fails

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.

Extensions don't load

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

Configuration changes don't apply

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.