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

# Declarative Providers

> Create LLM providers using JSON configuration files

Declarative providers allow you to add support for new LLM providers without writing Rust code. Simply define the provider's configuration in a JSON file.

## What are Declarative Providers?

Declarative providers are JSON configuration files that define:

* Provider metadata (name, description)
* API endpoint configuration
* Supported models and their capabilities
* Authentication requirements
* Protocol format (OpenAI-compatible, etc.)

Goose automatically loads these configurations and creates fully functional providers.

## Configuration File Structure

Declarative providers are located in `crates/goose/src/providers/declarative/`.

### Basic Structure

```json theme={null}
{
  "name": "provider_id",
  "engine": "openai",
  "display_name": "Provider Display Name",
  "description": "Brief description of the provider",
  "api_key_env": "PROVIDER_API_KEY",
  "base_url": "https://api.provider.com/v1/chat/completions",
  "models": [
    {
      "name": "model-name",
      "context_limit": 128000,
      "max_tokens": 4096
    }
  ],
  "supports_streaming": true
}
```

## Field Reference

### Required Fields

**name** (string)

* Unique identifier for the provider
* Used in configuration and CLI
* Must be lowercase, alphanumeric with underscores

```json theme={null}
"name": "groq"
```

**engine** (string)

* Protocol/format the provider uses
* Currently supported: `"openai"`
* Determines how requests are formatted

```json theme={null}
"engine": "openai"
```

**display\_name** (string)

* Human-readable name shown in UIs
* Can include spaces and special characters

```json theme={null}
"display_name": "Groq (d)"
```

**description** (string)

* Brief description of the provider
* Shown in provider selection UIs

```json theme={null}
"description": "Fast inference with Groq hardware"
```

**api\_key\_env** (string)

* Environment variable name for API key
* Convention: `PROVIDER_API_KEY` format

```json theme={null}
"api_key_env": "GROQ_API_KEY"
```

**base\_url** (string)

* API endpoint URL
* For OpenAI-compatible providers, include full path to chat completions

```json theme={null}
"base_url": "https://api.groq.com/openai/v1/chat/completions"
```

**models** (array)

* List of supported models
* See [Model Configuration](#model-configuration)

**supports\_streaming** (boolean)

* Whether the provider supports streaming responses
* Most modern providers support this

```json theme={null}
"supports_streaming": true
```

## Model Configuration

Each model in the `models` array defines:

```json theme={null}
{
  "name": "model-identifier",
  "context_limit": 131072,
  "max_tokens": 32768,
  "input_token_cost": 0.0000025,
  "output_token_cost": 0.00001
}
```

### Model Fields

**name** (string, required)

* Model identifier used in API requests
* Exact string the provider expects

**context\_limit** (integer, required)

* Maximum context window size in tokens
* Used for context management

**max\_tokens** (integer, required)

* Maximum output tokens per request
* Used to limit response length

**input\_token\_cost** (float, optional)

* Cost per input token in USD
* Used for cost estimation

**output\_token\_cost** (float, optional)

* Cost per output token in USD
* Used for cost estimation

## Complete Examples

### Groq Provider

```json theme={null}
{
  "name": "groq",
  "engine": "openai",
  "display_name": "Groq (d)",
  "description": "Fast inference with Groq hardware",
  "api_key_env": "GROQ_API_KEY",
  "base_url": "https://api.groq.com/openai/v1/chat/completions",
  "models": [
    {
      "name": "llama-3.3-70b-versatile",
      "context_limit": 131072,
      "max_tokens": 32768
    },
    {
      "name": "llama-3.1-8b-instant",
      "context_limit": 131072,
      "max_tokens": 131072
    },
    {
      "name": "qwen/qwen3-32b",
      "context_limit": 131072,
      "max_tokens": 40960
    }
  ],
  "supports_streaming": true
}
```

### Mistral Provider

```json theme={null}
{
  "name": "mistral",
  "engine": "openai",
  "display_name": "Mistral AI (d)",
  "description": "Mistral AI models",
  "api_key_env": "MISTRAL_API_KEY",
  "base_url": "https://api.mistral.ai/v1/chat/completions",
  "models": [
    {
      "name": "mistral-large-latest",
      "context_limit": 131072,
      "max_tokens": 32768,
      "input_token_cost": 0.000002,
      "output_token_cost": 0.000006
    },
    {
      "name": "mistral-small-latest",
      "context_limit": 32768,
      "max_tokens": 8192,
      "input_token_cost": 0.0000002,
      "output_token_cost": 0.0000006
    },
    {
      "name": "codestral-latest",
      "context_limit": 32768,
      "max_tokens": 8192,
      "input_token_cost": 0.0000002,
      "output_token_cost": 0.0000006
    }
  ],
  "supports_streaming": true
}
```

### DeepSeek Provider

```json theme={null}
{
  "name": "deepseek",
  "engine": "openai",
  "display_name": "DeepSeek (d)",
  "description": "DeepSeek AI models",
  "api_key_env": "DEEPSEEK_API_KEY",
  "base_url": "https://api.deepseek.com/v1/chat/completions",
  "models": [
    {
      "name": "deepseek-chat",
      "context_limit": 65536,
      "max_tokens": 8192,
      "input_token_cost": 0.00000014,
      "output_token_cost": 0.00000028
    },
    {
      "name": "deepseek-reasoner",
      "context_limit": 65536,
      "max_tokens": 8192,
      "input_token_cost": 0.00000055,
      "output_token_cost": 0.0000022
    }
  ],
  "supports_streaming": true
}
```

### Local Model Provider

```json theme={null}
{
  "name": "lmstudio",
  "engine": "openai",
  "display_name": "LM Studio (d)",
  "description": "Local models via LM Studio",
  "api_key_env": "LMSTUDIO_API_KEY",
  "base_url": "http://localhost:1234/v1/chat/completions",
  "models": [
    {
      "name": "local-model",
      "context_limit": 8192,
      "max_tokens": 2048
    }
  ],
  "supports_streaming": true
}
```

## Creating a New Declarative Provider

### 1. Create Configuration File

Create a new JSON file in `crates/goose/src/providers/declarative/`:

```bash theme={null}
touch crates/goose/src/providers/declarative/myprovider.json
```

### 2. Define Configuration

```json theme={null}
{
  "name": "myprovider",
  "engine": "openai",
  "display_name": "My Provider",
  "description": "Custom LLM provider",
  "api_key_env": "MYPROVIDER_API_KEY",
  "base_url": "https://api.myprovider.com/v1/chat/completions",
  "models": [
    {
      "name": "my-model-1",
      "context_limit": 128000,
      "max_tokens": 4096
    }
  ],
  "supports_streaming": true
}
```

### 3. Rebuild Goose

The provider is automatically loaded at build time:

```bash theme={null}
cargo build
```

### 4. Configure and Use

Set the API key:

```bash theme={null}
export MYPROVIDER_API_KEY=your-api-key
```

Configure Goose:

```bash theme={null}
goose configure --provider myprovider --model my-model-1
```

Start using:

```bash theme={null}
goose session
```

## OpenAI-Compatible APIs

Many providers offer OpenAI-compatible APIs. For these:

1. Set `"engine": "openai"`
2. Use the provider's base URL
3. Ensure model names match what the provider expects

Examples:

* Together AI
* Fireworks AI
* Anyscale Endpoints
* Modal
* Replicate (with OpenAI compatibility)

## Advanced Configuration

### Multiple Model Variants

Include all model variants with accurate limits:

```json theme={null}
"models": [
  {
    "name": "model-small",
    "context_limit": 8192,
    "max_tokens": 2048,
    "input_token_cost": 0.0000001,
    "output_token_cost": 0.0000002
  },
  {
    "name": "model-medium",
    "context_limit": 32768,
    "max_tokens": 4096,
    "input_token_cost": 0.0000005,
    "output_token_cost": 0.000001
  },
  {
    "name": "model-large",
    "context_limit": 131072,
    "max_tokens": 8192,
    "input_token_cost": 0.000002,
    "output_token_cost": 0.000004
  }
]
```

### Special Model Naming

Some providers use prefixes or special characters:

```json theme={null}
"models": [
  {
    "name": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "context_limit": 131072,
    "max_tokens": 8192
  },
  {
    "name": "openai/gpt-oss-120b",
    "context_limit": 131072,
    "max_tokens": 65536
  }
]
```

### Cost Tracking

Include accurate pricing for cost estimation:

```json theme={null}
{
  "name": "gpt-4o",
  "context_limit": 128000,
  "max_tokens": 16384,
  "input_token_cost": 0.0000025,
  "output_token_cost": 0.00001
}
```

Costs are per token in USD. Goose will:

* Track token usage
* Estimate costs per request
* Show cumulative costs

## Validation

### Testing Your Provider

After creating a declarative provider:

```bash theme={null}
# Build
cargo build

# Test configuration
goose configure --provider myprovider

# Test basic completion
goose session
> Hello, can you hear me?
```

### Common Issues

**Provider not found**

* Ensure JSON file is in `crates/goose/src/providers/declarative/`
* Rebuild: `cargo build`
* Check provider name matches filename (without `.json`)

**Authentication failed**

* Verify environment variable name matches `api_key_env`
* Check API key is set: `echo $MYPROVIDER_API_KEY`
* Ensure API key format is correct

**Model not found**

* Verify model name exactly matches provider's API
* Check provider documentation for exact model identifiers

**Context limit errors**

* Reduce `context_limit` if requests fail
* Check provider's actual model limits
* Some providers report limits differently

## Limitations

Declarative providers currently:

* Only support OpenAI-compatible APIs
* Cannot implement custom OAuth flows
* Cannot handle complex authentication schemes
* Cannot customize request/response transformation

For providers requiring these features, implement a [custom provider](/development/provider-interface).

## Contributing Declarative Providers

To add a provider to Goose:

1. Create the JSON configuration file
2. Test thoroughly
3. Document model capabilities accurately
4. Submit a PR to the Goose repository
5. Include example usage in PR description

See [Contributing Guide](/development/contributing) for details.

## Existing Declarative Providers

Goose includes these declarative providers:

* **Groq** - Fast inference
* **Mistral** - Mistral AI models
* **DeepSeek** - DeepSeek models
* **Cerebras** - Cerebras inference
* **Moonshot** - Moonshot AI
* **Kimi** - Kimi models
* **LM Studio** - Local model hosting
* **OVHcloud** - OVHcloud AI endpoints

See `crates/goose/src/providers/declarative/` for complete configurations.

## Next Steps

* Learn about [OAuth Providers](/development/oauth-providers)
* Implement [Custom Providers](/development/provider-interface)
* Read about [Provider Architecture](/development/architecture)