Home›Provider tutorials

Configure Groq in DeepSeek Harness

Connect Groq through its OpenAI-compatible Chat Completions endpoint, then select an active Groq model.

On this page

Use the current model list first

The endpoint, protocol and environment variable below come from the provider's official documentation or the current upstream provider source. Model catalogs change, so use the ID shown by your installed DSH version.

Before you start

Make sure DSH is already running from npx @deepseek-ai/dsh web; the default Web UI address is http://127.0.0.1:3080. If DSH itself does not start, use the startup checks first.

Keep the API key private

Do not put a real key in a repository, screenshot, prompt or public error report.

STEP 1

Get a Groq API key

Open Groq API keys, sign in, create a key and copy it before leaving the page.

Environment variable

If you use YAML, the variable name must exactly match the apiKeyEnv value below; the variable name is not the key itself.

STEP 2

Add the provider to DSH

Open Settings → Models. If Groq appears in the installed catalog, choose Add provider, paste the API key and save it.

Choose Groq under Add provider when your installed catalog exposes it. The official OpenAI-compatible base URL is `https://api.groq.com/openai/v1`, and the route uses Chat Completions.

A restart is not the first fix

The official provider guide says model and provider changes take effect on the next request. Save, then start a fresh session for the test.

STEP 3

Check the route values

Route	Provider ID	apiKeyEnv	Base URL	API
Groq · built-in	`groq`	`GROQ_API_KEY`	`https://api.groq.com/openai/v1`	`openai-completions`

Do not mix a key from one region or plan with another route or protocol. Use a built-in row only when that catalog is actually present in your DSH version.

STEP 4

Select a model

Groq's current API examples use `openai/gpt-oss-20b`. Treat it as a live documentation example and confirm it under `GET /openai/v1/models` for your account before selecting it.

openai/gpt-oss-20b

Copy the Model ID, not the page title

If a model is missing from the picker, do not keep guessing names. For an OpenAI-compatible custom route, use Fetch available models; if discovery fails, add the exact ID returned by the provider manually.

If the built-in catalog is missing: create a custom provider

Open Settings → Models → Add a custom provider. Use a lowercase Provider ID and choose it carefully, for example groq-custom.

Base URL

https://api.groq.com/openai/v1

API protocol

openai-completions

Credential

GROQ_API_KEY holds the key

Models

Click Fetch available models, search and choose Add selected.

If the endpoint does not return a model list, confirm the key, base URL and model ID, then add it manually. Failed discovery does not by itself prove that chat requests fail.

If you need YAML

The Web UI is enough for a normal setup. Edit <code>$DSH_HOME/settings.yaml</code> only when you need a fixed custom route or a setting the form cannot express. Replace the model ID below with the exact value returned by the provider.

llm-pi-ai:
  providers:
    groq-custom:
      apiKeyEnv: GROQ_API_KEY
      api: openai-completions
      baseURL: https://api.groq.com/openai/v1
      models:
        - id: <copy the exact model id from the provider>

Reference the key through <code>apiKeyEnv</code>; do not put the secret itself in the config file. A custom route's <code>models</code> list replaces that route's model catalog.

Test one safe request

Choose a disposable test workspace, start a fresh session, select the configured model and send:

Reply with “Groq connected”. Do not edit files or run commands.

Once the reply is successful, move on to file-reading or tool tasks. This keeps credential and routing failures separate from workspace and permission issues.

Common errors

MISSING_CREDENTIAL

Return to Settings → Models and save the key. With YAML, make sure the variable named by apiKeyEnv existed before DSH started.

UNKNOWN_MODEL

Use a Model ID that actually exists under the current provider. Do not substitute a display name, alias or an old tutorial's model name.

401 / authentication failed

Do not put `/chat/completions` into Base URL. DSH appends the operation path. If the built-in card is absent, use a custom provider with `openai-completions`.

Fetch available models is empty or fails

Check the base URL, protocol and key currently shown in the form. If the provider does not expose a compatible model-list endpoint, confirm the model ID and add it manually.

The old model still appears to be used

A session that has already sent a request keeps its own recorded model. Start a new session when verifying the switch.

NEXTBrowse all provider tutorials

Back to the list →

Primary sources

Groq OpenAI compatibility · Groq API reference · Groq provider source · DeepSeek Harness Provider guide