# Coordinator model providers

Run OSS Coordinator with DeepSeek, OpenAI, Anthropic, Google or a compatible endpoint.

Provider configuration belongs to the engine process. The API key stays server-side. Enabling Coordinator is a separate, versioned public API call described in [OSS Coordinator](https://beepgrid.com/docs/guides/coordinator.md).

## Supported settings

| Variable | Required/default | Usage |
| --- | --- | --- |
| `BEEPGRID_AI_PROVIDER` | Required when using built-in adapters | `openai`, `anthropic`, `google`, `openai-compatible` |
| `BEEPGRID_AI_MODEL` | Required, no default model | Explicit provider model ID |
| `BEEPGRID_AI_API_KEY` | Required except compatible local endpoints that need no key | Provider secret; load from your secret store |
| `BEEPGRID_AI_BASE_URL` | Required for `openai-compatible`; provider default otherwise | Base URL without query, fragment or embedded credentials |
| `BEEPGRID_AI_OUTPUT_MODE` | `schema`; compatible default is `json` | `schema`, `json`, or `text`; Anthropic does not accept `json` mode |
| `BEEPGRID_AI_OPTIONS` | Optional JSON object, at most 8 KiB | Provider-specific allowlisted generation controls, not arbitrary tools or prompts |
| `BEEPGRID_AI_ALLOW_PRIVATE` | `false` | Explicitly allow your deliberately configured private/local model address |

Default base URLs are OpenAI `https://api.openai.com/v1`, Anthropic `https://api.anthropic.com/v1` and Google `https://generativelanguage.googleapis.com/v1beta`. The compatible adapter calls `/chat/completions`; OpenAI uses `/responses`, Anthropic `/messages` and Google its model generate-content endpoint.

## DeepSeek example

Load `BEEPGRID_AI_API_KEY` securely in the engine environment, then configure:

```sh
export BEEPGRID_AI_PROVIDER=openai-compatible
export BEEPGRID_AI_BASE_URL=https://api.deepseek.com
export BEEPGRID_AI_MODEL=deepseek-flash
export BEEPGRID_AI_OUTPUT_MODE=json
export BEEPGRID_AI_OPTIONS='{"max_tokens":4096}'
.local/beepgrid serve --no-ui
```

The model ID above follows the current [DeepSeek API documentation](https://api-docs.deepseek.com/). Select a model available to your account; provider model availability can change. DeepSeek's [JSON mode requirements](https://api-docs.deepseek.com/guides/json_mode/) apply. The adapter supplies JSON instructions and validates the result; malformed or incomplete output fails closed.

This configuration is supported through the compatible adapter. Repository qualification uses a local deterministic compatible endpoint; it does not claim that this exact DeepSeek model has been live-qualified.

## Local compatible model

Use your own reachable endpoint and actual served model ID:

```sh
export BEEPGRID_AI_PROVIDER=openai-compatible
export BEEPGRID_AI_BASE_URL=http://127.0.0.1:8000/v1
export BEEPGRID_AI_MODEL=your-served-model-id
export BEEPGRID_AI_OUTPUT_MODE=json
export BEEPGRID_AI_ALLOW_PRIVATE=true
```

Inside Docker, loopback refers to the engine container; use your model service's reachable hostname instead. Only enable private access deliberately. The model must reliably return the Coordinator schema, including selected agent IDs from the supplied context.

## Generation controls and failure behavior

Supported `BEEPGRID_AI_OPTIONS` keys are:

| Provider | Keys |
| --- | --- |
| OpenAI | `max_output_tokens`, `temperature`, `top_p`, `reasoning`, `service_tier`, `text` |
| Anthropic | `max_tokens`, `temperature`, `top_p`, `top_k`, `thinking`, `output_config` |
| Google | `maxOutputTokens`, `temperature`, `topP`, `topK`, `seed`, `thinkingConfig`, `stopSequences` |
| OpenAI-compatible | `max_tokens`, `max_completion_tokens`, `temperature`, `top_p`, `top_k`, `min_p`, `seed`, `frequency_penalty`, `presence_penalty`, `reasoning_effort`, `reasoning`, `thinking`, `repeat_penalty`, `stop` |

Nested objects are restricted: `text` allows `verbosity`; `output_config` allows `effort`; `thinking` allows `type` and `budget_tokens`; `thinkingConfig` allows `thinkingBudget`, `thinkingLevel` and `includeThoughts`. `reasoning` allows `effort` and `summary` for OpenAI, and also `enabled`/`max_tokens` for compatible endpoints. Output token limits are integers from 1 through 65,536. The adapter owns model selection, schema/JSON formatting, tool exclusion and stream behavior; unsupported or reserved keys are rejected. A provider may reject a generation control that its selected model does not support. Keep those errors distinct from a communication failure.

Model calls have a 30-second server timeout, bounded context and strict result validation. The engine does not silently switch providers or retry model calls. Provider setup being valid does not mean a real exchange succeeded; verify planning, dispatch and returned specialist replies with your chosen model.

For a separately hosted custom assistance gateway, the retained `BEEPGRID_OVERSEER_URL` and `BEEPGRID_OVERSEER_TOKEN` configure the legacy engine-specific gateway contract and override the built-in Coordinator adapter. They are not the settings for an ordinary OpenAI-compatible endpoint.