How to use OpenRouter in DeepSeek Harness

OpenRouter is the fastest way to try many models without opening accounts everywhere. It is OpenAI-compatible, so DSH treats it as a Custom model API speaking OpenAI Chat Completions.

Before you start

You need a partially funded OpenRouter account, an API key, and Node.js installed. If DSH itself is not running yet, do the install guide first.

Step 1 — create an API key

Sign in to OpenRouter and create a key in its console. Copy it once — most providers never show it again.

Open OpenRouter →

Step 2 — start the harness

npx @deepseek-ai/dsh web

Web UI comes up at http://127.0.0.1:3080.

Step 3 — Add model provider → Custom model API

In Settings → Models, choose Add model provider, then switch the card to Custom model API — that is the route for a relay, a company gateway, or any provider absent from the installed catalog. Fill in:

The Provider ID is permanent — requests, saved sessions, model defaults and credential references all use it. To rename a provider you add a new one and delete the old one; everything except the ID stays editable.

A provider speaks exactly one protocol. A gateway that serves both OpenAI and Anthropic formats needs two separate provider entries.

Step 4 — add at least one model

Use Fetch available models to ask the endpoint what it serves — the request uses the base URL, protocol and key currently in the form. It reads the listing formats common gateways publish, but not every endpoint answers in one of them, so when it fails or lists nothing, add the ids by hand and they work the same.

Known-good ids:

• deepseek/deepseek-chat
• anthropic/claude-sonnet-4
• moonshotai/kimi-k2

Step 5 — verify

Save, then select the model in the composer. Model changes apply on the next request; no restart.

Or: configure it in YAML

The Web UI writes the same document you can edit directly. The profile for a standard dsh web launch is web, so the file is $DSH_HOME/profiles/web/cordis.patch.yml. Adapters re-read it on the next request — no restart needed.

# $DSH_HOME/profiles/web/cordis.patch.yml
- id: llm-pi-ai
  config:
    providers:
      openrouter:
        apiKeyEnv: DSH_API_KEY
        api: openai-completions
        baseURL: https://openrouter.ai/api/v1
        models:
          - id: deepseek/deepseek-chat

A Cordis config override replaces the complete entry config — when editing an existing override, preserve your other providers and fields or they vanish.

Export the variable referenced above in the shell that starts DSH:

export DSH_API_KEY="sk-..."

Troubleshooting

• 404 on every request — the base URL is wrong. It must end at the version segment (/v1), never at /chat/completions.
• 401 Unauthorized — key revoked, or pasted with trailing whitespace. Note that DSH's env-var detection does not validate the key.
• CLIENT_UPGRADE_REQUIRED — the model needs a newer harness. The error names the version to install.
• Model missing from the picker — a saved default pointing at a deleted provider makes the composer show Select model and block input until you pick another.
• Empty or truncated reply — usually the model id resolved to a different model than you expected. Add the id explicitly rather than relying on Fetch available models.

Cost and caveats

Per token at the underlying provider's price, plus a small fee on credit top-ups. No monthly minimum.

• Model IDs carry a vendor prefix and a slash: deepseek/deepseek-chat.
• Free-tier models exist but are heavily rate-limited — unusable for unattended agents.
• The base URL already contains /api/v1. Do not append /chat/completions yourself.

Plugins that pair well with this provider

Other providers

Source for every field above: the official DSH provider docs. If DSH changes a field name, that document wins over this page.