DeepSeek Harness custom model editorial cover: two configuration paths, a Web UI form and a settings.yaml file, feeding an OpenAI-compatible gateway with an amber key

DeepSeek Harness Custom Model: pure configuration, no plugin required

You can point DeepSeek Harness at any OpenAI-compatible provider, and the “custom model” part is nothing but configuration. The harness’s llm-pi-ai adapter accepts a custom provider for any OpenAI-compatible endpoint:

Modellix needs no plugin—only configuration. — Modellix DeepSeek Harness docs

Four values define a model source: provider ID, base URL, API protocol, and model IDs. Get those right and the harness talks to the new source on the next request, no restart, no bundle to install.

This article covers exactly that configuration path: the five-field Web UI form and the equivalent $DSH_HOME/settings.yaml block, side by side, with real values and the complete list of 28 model IDs you can select. It does not cover where keys live and how to rotate them, and it does not cover installing plugins. The plugin path is a separate decision—if you need image and video generation, web search and fetch, or a live model catalog that syncs into the model selector, that is what the Modellix plugin for DeepSeek Harness is for. This page is the “just swap the model source” half of that pair.

One disclosure up front: Modellix runs the LLM gateway used in these examples, so we have a commercial interest in this configuration working for you. The instructions below come from our own documentation and the official Harness providers guide, and the numbers are dated August 30, 2026.

What a custom model source needs from you

Before you open the form, make sure the prerequisites are in place:

  • DeepSeek Harness Web UI is running. Start it with npx @deepseek-ai/dsh web from the official repository, or build from source per the root README.
  • A Modellix API key from the console—at https://www.modellix.ai/console/api-key. The key must be a Modellix key, not a vendor platform key: an OpenAI, Anthropic, or DeepSeek platform key will not authenticate against llm.modellix.ai.
  • A workspace selected in the harness, so the session composer is available.

A DeepSeek Harness custom provider is defined by four things, and this article is organized around exactly those four:

What Where it lives Example for Modellix
Provider ID form field / YAML key under providers: modellix
Base URL form field / baseURL https://llm.modellix.ai/v1
API protocol form field / api openai-completions
Model IDs form list / models[].id openai/gpt-5.6-sol

Model changes take effect on the next request; you do not need to restart the server. This applies to both paths below, and it is also the reason a saved provider “just works” later—the harness reads the configuration per request.

The official DeepSeek Harness providers guide documents the same custom-provider mechanism generically. What follows is that mechanism applied to a real gateway, with values you can copy.

Option A — the five-field Web UI form

Open Settings → Models and choose Add a custom provider. The form has five fields:

Field Value
Provider ID modellix (lowercase; permanent once saved)
Display name Modellix
Base URL https://llm.modellix.ai/v1
API protocol openai-completions (OpenAI Chat Completions)
API key Your Modellix API key
DeepSeek Harness custom provider form with Provider ID, display name, base URL, API protocol, and API key fields pointing at the Modellix LLM gateway

The five fields of the custom provider form as documented for the Modellix gateway: Provider ID, display name, base URL, API protocol, and API key.

Three things about this form are easy to miss:

  • The Provider ID is permanent once saved. Requests, saved sessions, model defaults, and credential references all use it. The display name, base URL, protocol, credential, and models stay editable—the Provider ID does not. There is no rename; you add a new provider and delete the old one. More on this in the traps section.
  • Keys are write-only. After saving, the page shows only a redacted descriptor, and the key is stored in $DSH_HOME/.credentials.yaml—not ~/.dsh/.credentials.yaml. Settings files keep only a credential reference, never the literal secret.
  • “Fetch available models” does a live query. The Modellix gateway serves the OpenAI-compatible GET /v1/models endpoint, so the form can list current model IDs automatically. Select the ones you want, or enter them by hand. The provider is not stored until you save.

After saving, pick a Modellix model in the model picker. Selecting a model also makes it the default for new sessions.

Option B — the same provider in $DSH_HOME/settings.yaml

You can declare the exact same provider in $DSH_HOME/settings.yaml instead of the form. The deepseek harness settings yaml route is equivalent to the form above: same provider, same fields, same semantics. Credentials stay out of this file—apiKeyEnv is a reference that is resolved per request (or you can provide the key through the Models page):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
llm-pi-ai:
  providers:
    modellix:
      apiKeyEnv: MODELLIX_API_KEY
      api: openai-completions
      baseURL: https://llm.modellix.ai/v1
      models:
        - id: openai/gpt-5.5
          name: GPT 5.5
        - id: openai/gpt-5.6-sol
          name: GPT 5.6 Sol
        - id: anthropic/claude-sonnet-5
          name: Claude Sonnet 5
        - id: google/gemini-3.6-flash
          name: Gemini 3.6 Flash
        - id: deepseek/deepseek-v4-flash
          name: DeepSeek V4 Flash
settings.yaml llm-pi-ai provider block mapping apiKeyEnv, api, baseURL and models to the Modellix LLM gateway endpoint

The settings.yaml route block: apiKeyEnv resolves the credential, api selects the wire protocol, baseURL points at the gateway, and models is the catalog the route will serve.

Field-by-field:

Field Meaning
apiKeyEnv Environment variable holding the Modellix API key
api Wire protocol; openai-completions for Chat Completions
baseURL https://llm.modellix.ai/v1
models List of model entries; id is the exact Modellix model ID sent on the wire

Two semantics in that block matter more than they look:

  • The models list replaces the route’s catalog—it does not append to it. Every model the route should serve must appear in the list; an entry with only id is enough, and name is optional (it is what selectors show). Add or remove entries as needed. A model the route does not configure fails with UNKNOWN_MODEL.
  • Each id must be the full Modellix model ID, including the provider/ prefix—openai/gpt-5.6-sol, not gpt-5.6-sol. The harness sends the string unchanged in the request body, and the gateway routes on the full ID. The full list of valid IDs is the next section.

The 28 model IDs you can select

The Modellix LLM gateway currently exposes 28 language models across 9 provider labels. This is the full deepseek harness model list for the gateway as of August 30, 2026—these are the IDs you put in the form’s model list or in models[].id:

Provider Model IDs
Anthropic anthropic/claude-haiku-4.5 · anthropic/claude-opus-5 · anthropic/claude-sonnet-5
DeepSeek deepseek/deepseek-v4-flash · deepseek/deepseek-v4-flash-vision · deepseek/deepseek-v4-pro
Google google/gemini-3.1-pro · google/gemini-3.5-flash · google/gemini-3.6-flash · google/gemini-3.7-flash
modellix-ai modellix-ai/free-llm
Moonshot moonshot/kimi-k2.7 · moonshot/kimi-k3
OpenAI openai/gpt-5.5 · openai/gpt-5.6-luna · openai/gpt-5.6-sol · openai/gpt-5.6-terra
Qwen qwen/qwen3.7-max · qwen/qwen3.7-plus · qwen/qwen3.8-flash · qwen/qwen3.8-max
xAI xai/grok-4.3 · xai/grok-4.5 · xai/grok-4.6
ZAI zai/glm-4.7-flash · zai/glm-5.2 · zai/glm-5.3 · zai/glm-5.3-flash
Modellix LLM model catalog with 28 model IDs grouped by nine provider labels for the DeepSeek Harness model list

The full Modellix LLM catalog: 28 model IDs in provider/name form, grouped by their nine provider labels, as of August 30, 2026.

Three notes on the list:

  • Every ID is provider/name. Copy them verbatim. The harness sends exactly what you type, and the gateway’s Models & Pricing reference is the canonical list to check when this table ages.
  • Prices are per 1M tokens and change. Billing is in USD per 1M tokens for input, output, and cache reads/writes, with per-model rates shown on the live Modellix LLM page. This article intentionally does not quote rates—they move, and the live table is the source of truth.
  • Latest aliases exist, with a naming asymmetry. The gateway supports ~provider/series-latest stable aliases. As of August 30, 2026, ~anthropic/claude-opus-latest routes to anthropic/claude-opus-5, while ~anthropic/sonnet-latest and ~anthropic/haiku-latest route to anthropic/claude-sonnet-5 and anthropic/claude-haiku-4.5—note that one carries the claude- prefix and the other two do not. That asymmetry is real, so don’t “fix” it. DeepSeek and modellix-ai have no latest aliases. Targets change as each family evolves, so treat any alias mapping as dated.

Which models should you put in the list?

There is no rule that says you must add all 28. The list is your route’s catalog, and a smaller list means fewer models to audit when the gateway’s catalog changes. Three practical defaults:

  • Start with two to four models covering the workloads you actually run—say openai/gpt-5.6-sol for hard reasoning, anthropic/claude-sonnet-5 for long agent turns, and deepseek/deepseek-v4-flash for cheap bulk work.
  • Use a ~latest alias when you want a family to track its newest release without editing config, and pin a concrete ID when you need reproducible results—the gateway’s own guidance for evaluations and regression tests is to use a fixed ID such as openai/gpt-5.6-sol.
  • Context windows vary a lot—from 200K tokens (anthropic/claude-haiku-4.5, modellix-ai/free-llm) up to 1,310,720 tokens (zai/glm-5.3-flash). If your agent feeds large repos into context, check the window before you pick the default model; the Models & Pricing page lists it per model.

The Anthropic protocol variant: api: anthropic-messages

Most setups should keep openai-completions: every Modellix model, including the anthropic/... ones, works over Chat Completions at https://llm.modellix.ai/v1. That is the OpenAI-compatible path, and it answers the deepseek harness openai compatible question directly: one protocol for the whole catalog.

If you prefer the Anthropic wire protocol, change two values:

1
2
3
4
5
6
7
8
9
llm-pi-ai:
  providers:
    modellix:
      apiKeyEnv: MODELLIX_API_KEY
      api: anthropic-messages
      baseURL: https://llm.modellix.ai
      models:
        - id: anthropic/claude-sonnet-5
          name: Claude Sonnet 5

Two differences from the main path, both easy to get wrong. The deepseek harness base url rule is protocol-dependent, and this is the one place it differs from the OpenAI path:

  • baseURL is https://llm.modellix.ai with no /v1. The Anthropic Messages endpoint is POST /v1/messages, and the harness appends the path itself. The LLM API guide states this explicitly: OpenAI-compatible clients include /v1; Anthropic clients do not.
  • Model discovery stops working. Fetch available models only reads OpenAI-compatible GET /models endpoints, so on this protocol the form cannot auto-list models—enter the model IDs by hand. Your models list is now the only catalog the route has.

The four traps that cause “model won’t connect”

The biggest model-side complaint in the harness community is “model won’t connect” reports (a 27-comment GitHub Discussions thread is the largest on the topic). In practice, four configuration mistakes account for most of them. Each maps to a specific line in the harness or gateway response:

Trap 1: the Provider ID is permanent once saved

The modellix Provider ID is baked into requests, saved sessions, model defaults, and credential references at save time. If you later decide the ID should be different, you cannot rename it—the harness’s own docs say to add a new provider and delete the old one. Choose the ID carefully on day one; it is the one field you cannot change later.

Trap 2: the models list replaces the route’s catalog

This is the most common UNKNOWN_MODEL cause. The list is not a filter on a bigger built-in catalog—it is the catalog. Concretely: you configure the route with openai/gpt-5.5 only, run a session, then edit settings.yaml down to that single entry; when the saved session resumes and asks for openai/gpt-5.6-sol (a model the session had used earlier), the route no longer configures it and the request fails with UNKNOWN_MODEL. Sessions retain the model recorded in their own logs, so a changed list can invalidate an old session. The fix is always the same: add the missing model to the custom provider, or select a configured one.

Trap 3: model IDs must carry the provider/ prefix

gpt-5.6-sol is not a valid model on the gateway; openai/gpt-5.6-sol is. The harness sends the id string unchanged, and the gateway routes on the full provider/name form. A missing prefix produces a 404-style “unknown model” response that looks like a connectivity problem.

Trap 4: Anthropic protocol means no /v1 and no auto-discovery

If you switch api to anthropic-messages but leave the base URL at https://llm.modellix.ai/v1, requests fail—the client appends /v1/messages to whatever base URL you gave it, producing a doubled path. And because model discovery reads only OpenAI-compatible GET /models, a correctly configured Anthropic route with an empty models list has no models at all. Enter IDs by hand.

Reading the error lines

Error Most likely cause Fix
MISSING_CREDENTIAL No key stored for the provider, or MODELLIX_API_KEY not set in the harness environment Store the key through the Models page, or provide the referenced environment variable
UNKNOWN_MODEL Model not in the route’s models list (the list replaces the catalog) Add the missing model to the custom provider, or select a configured one
Fetch available models returns 401 The key is wrong, or it is a vendor platform key rather than a Modellix key Check the key in the Modellix console (linked in the prerequisites); enter models manually if needed

These three rows cover the configuration errors you can hit on this path. The gateway’s own API reference adds the protocol-level rules (auth headers, base URL per protocol, request body shapes) if a request passes configuration and still fails—that guide is linked in the previous section.

When configuration is not enough: the plugin path

Pure configuration swaps the model source—and that is all it does. The plugin path exists for everything else the harness can do with a gateway:

  • Design: image, video, and audio generation from inside the harness, on the media API (a different host from the text gateway, with async tasks).
  • Web: native web_search and web_fetch providers backed by the Modellix tool API, without building custom tools.
  • Live catalog: a model selector that keeps syncing the current model list, instead of the snapshot you configure once here.

If those capabilities matter to your setup, the Modellix plugin for DeepSeek Harness article (linked in the first section) walks through installing the bundle, storing the key, and what each module does. If you only need a different model source, you are already done—the form or the YAML block above is the whole change. For context on why a single key and one integration path exist at all, the unified AI API guide explains the aggregator model behind it.

DeepSeek Harness Integration Docs

Read the full DeepSeek Harness configuration reference for the Modellix LLM gateway, including the Anthropic protocol variant and the troubleshooting table.

View Docs

Open the Modellix Console

Log in to generate your Modellix API key and check live per-million-token pricing for all 28 models.

Login

Configuration instructions verified against the Modellix DeepSeek Harness documentation and the official Harness providers guide on August 30, 2026. Model catalogs, prices, and alias targets change as providers evolve; check the live Models & Pricing page before relying on a specific ID. Modellix operates the gateway described in this article and has a commercial interest in it. The Modellix LLM gateway is a text gateway—use text-only prompts; do not attach images.