> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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

<Tip>
  The configuration wizard automatically validates your credentials by making a test API call to ensure everything is working.
</Tip>

### Modifying Configuration

Run `goose configure` again to modify settings:

```bash theme={null}
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.

<Tabs>
  <Tab title="OpenAI">
    **Required Environment Variable:**

    ```bash theme={null}
    export OPENAI_API_KEY="sk-..."
    ```

    **Optional Configuration:**

    ```bash theme={null}
    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`
  </Tab>

  <Tab title="Anthropic">
    **Required Environment Variable:**

    ```bash theme={null}
    export ANTHROPIC_API_KEY="sk-ant-..."
    ```

    **Optional Configuration:**

    ```bash theme={null}
    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`
  </Tab>

  <Tab title="Databricks">
    Databricks supports both token and OAuth authentication.

    **Token Authentication:**

    ```bash theme={null}
    export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
    export DATABRICKS_TOKEN="dapi..."
    ```

    **OAuth Authentication:**

    ```bash theme={null}
    export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
    # Run goose configure to complete OAuth flow
    ```

    Models are automatically discovered from your workspace.
  </Tab>
</Tabs>

See the [Providers overview](/api/providers/overview) for a complete list of supported providers and their configuration options.

### Local Inference

For local models using Ollama:

```bash theme={null}
export GOOSE_PROVIDER="ollama"
# Optional: if Ollama is running on a different host
export OLLAMA_HOST="http://localhost:11434"
```

Then pull a model:

```bash theme={null}
ollama pull qwen3.2
```

Goose will automatically detect available models.

Learn more in the [Local Inference guide](/advanced/local-inference).

## Configuration Files

Goose stores configuration in several locations:

### Config Directory

<Tabs>
  <Tab title="macOS/Linux">
    ```
    ~/.config/goose/
    ├── config.yaml          # Provider and extension configuration
    └── .goosehints          # Project-specific hints
    ```
  </Tab>

  <Tab title="Windows">
    ```
    %APPDATA%\goose\
    ├── config.yaml
    └── .goosehints
    ```
  </Tab>
</Tabs>

### config.yaml Structure

```yaml theme={null}
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
```

<Warning>
  Do not store API keys or secrets in `config.yaml`. Use environment variables or the secure keyring storage instead.
</Warning>

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

```bash theme={null}
# 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](/guides/environment-variables) 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**

<Info>
  This allows you to override configuration temporarily without modifying files.
</Info>

## Extension Configuration

### Adding Extensions

During `goose configure`, you can add MCP servers:

```bash theme={null}
goose configure
# Select "Extensions" > "Add extension"
```

Or manually edit `config.yaml`:

```yaml theme={null}
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](/guides/mcp-integration) for detailed extension configuration.

## Testing Your Configuration

After configuration, test that everything works:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="CLI Usage" icon="terminal" href="/guides/cli-usage">
    Learn how to use the goose command-line interface
  </Card>

  <Card title="Desktop App" icon="desktop" href="/guides/desktop-app">
    Explore the graphical desktop application
  </Card>

  <Card title="Environment Variables" icon="sliders" href="/guides/environment-variables">
    Complete reference for environment variable configuration
  </Card>

  <Card title="Extensions" icon="puzzle-piece" href="/guides/mcp-integration">
    Add custom tools and capabilities to goose
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

For more help, see the [Troubleshooting guide](/troubleshooting/diagnostics) or ask in our [Discord community](https://discord.gg/goose-oss).