# DeepSeek Harness

> Point DeepSeek's open-source agent harness (dsh) at Tokens as a custom OpenAI-compatible provider, keep the key in an environment variable, and run DeepSeek models or the rest of the catalog through the agent loop.

# DeepSeek Harness

> Point DeepSeek's open-source agent harness (`dsh`) at Tokens as a custom OpenAI-compatible provider, keep the key in an environment variable, and run DeepSeek models — or the rest of the catalog — through the agent loop.

DeepSeek Harness is DeepSeek AI's open-source agent runtime, invoked as `dsh` (released August 2026). The model does the thinking; the harness runs the loop around it — tools, shell, files, sessions, sandboxing and context — with almost everything wired up as replaceable Cordis plugins. It ships a CLI, a TUI and a Web UI, plus Standard, Code, Minimal and Creator modes.

`dsh` runs any OpenAI-compatible endpoint, so it points at Tokens with a config change and no extra plugins. Create a key at [your dashboard](/dashboard/keys) if you don't have one. [API keys](/docs/api-keys) explains spend caps and model allow-lists.

## Install dsh

:::code-tabs

```bash title="Linux / macOS / WSL2"

npm install -g @deepseek-ai/dsh

```

```powershell title="Windows PowerShell"

npm install -g @deepseek-ai/dsh

```

:::

That installs the `dsh` command. `dsh web` starts the Web UI on your machine. Your settings live in `$DSH_HOME/settings.yaml` (default `~/.dsh/settings.yaml`) — the same file the Web UI writes.

## Option A: the Web UI

The fastest path. Run `dsh web`, open the UI, and go to **Settings → Models**:

1. Click **Add custom provider**.
2. Fill in the form:
   - **Provider ID:** `tokens` (lowercase, stable)
   - **Display name:** `Tokens`
   - **Base URL:** `https://tokens.bd/v1`
   - **API protocol:** `openai-completions`
   - **API key:** your `tok_live_...` key
3. Click **Fetch available models** to pull Tokens' model list, or add a model manually with its full id (e.g. `deepseek/deepseek-v4.1-flash`).
4. Save, then pick the provider and model in the chat tab's model picker.

## Option B: edit $DSH_HOME/settings.yaml

Point the built-in DeepSeek adapter at Tokens. No code changes needed:

```yaml title="$DSH_HOME/settings.yaml"

llm-deepseek:
  baseURL: https://tokens.bd/v1
  apiKeyEnv: TOKENS_API_KEY
  models:
    - id: deepseek/deepseek-v4.1-flash
      name: DeepSeek V4.1 Flash (via Tokens)
      contextWindow: 1000000
agent-default-model:
  provider: deepseek-official
  model: deepseek/deepseek-v4.1-flash

```

Three points to get right:

- **`baseURL` is the gateway root.** `/chat/completions` is appended automatically, so end it at `/v1` — not at `/v1/chat/completions`.
- **The model id must carry the `provider/` prefix.** Tokens routes on the full id (`deepseek/deepseek-v4.1-flash`); the bare name is rejected. Copy ids from [/models](/models) or `GET /v1/models`.
- **The key resolves from the environment** named by `apiKeyEnv` on every request. Export it in the shell that starts `dsh`:

:::code-tabs

```bash title="macOS / Linux"

export TOKENS_API_KEY="tok_live_your_key"

```

```powershell title="Windows PowerShell"

$env:TOKENS_API_KEY="tok_live_your_key"

```

:::

Changes take effect on the next request — no restart needed. To go back to the official DeepSeek endpoint, edit `settings.yaml` again or pass `--model` / `--provider` for a single session.

## Switch models

Change `models[].id` and `agent-default-model.model` to another id from [/models](/models) or `GET /v1/models`, and update `contextWindow` to the model's real window (DeepSeek V4/V4.1 Flash models carry 1M). Tokens isn't limited to DeepSeek models: any id in the catalog works through the same adapter, since the gateway translates the request for the upstream provider.

Inside the CLI, `/model <model>` switches the model for the current session.

[Choosing a model](/docs/choosing-a-model) helps you pick an agent-suitable model: look for tool calling support and a context window your workload fits in.

## Verify it works

```bash

dsh "Reply with the single word OK"

```

It should answer once and exit. If it starts looping or its tool calls fail, the model likely lacks OpenAI-style tool calling — switch to another model.

## Troubleshooting

**401 or `MISSING_CREDENTIAL`.** The env var named in `apiKeyEnv` isn't visible to `dsh`. Check the spelling and that it was exported in the shell that launched the harness.

**Model not found / gateway rejects the request.** The model id is missing its `deepseek/` (or other provider) prefix. Use the full id from [/models](/models).

**Context window looks wrong.** Set `contextWindow` explicitly in `settings.yaml` — dsh trusts your config first. Copy the real value from [/models](/models).

**403 `model_not_allowed_on_key` or 429 `window_exhausted`.** These are key and plan limits, not harness errors. See [Error code reference](/docs/errors) for every error code.

**Web search inside dsh.** The built-in `web_search` tool speaks the Anthropic-compatible Messages API. Point it at Tokens' Anthropic-compatible endpoint (`https://tokens.bd` — SDKs append `/v1/messages`), following the base-URL rules in [Authentication](/docs/authentication).

---

---
Page: https://tokens.bd/docs/deepseek-harness