DeepSeek Harness - Nbility AI Gateway

This guide explains how to connect DeepSeek Harness (dsh) to Nbility by configuring Nbility as a custom OpenAI-compatible provider. After setup, one Nbility API key can access Claude, GPT, Gemini, DeepSeek, Kimi, MiniMax, GLM, Grok, and other models available on the platform.

Note: DeepSeek Harness is currently in developer preview and evolves quickly. Future releases may include breaking changes. This guide is based on the official README and model configuration guide, adapted for Nbility.

What is DeepSeek Harness?

DeepSeek Harness is an open-source agent harness developed by DeepSeek AI. It uses an “everything is a plugin” architecture powered by Cordis. Its primary interface is the browser-based Web UI (dsh web), while the same home directory also supports one-off headless tasks.

Official project links:

Prerequisites

An Nbility account
An Nbility API key
Node.js installed (required for npx)
A terminal on macOS, Linux, or Windows

Install and start

The recommended way to start Harness is with npx. First, open the project directory where you want the agent to work:

npx @deepseek-ai/dsh web

The Web UI listens on http://127.0.0.1:3080 by default. The launch directory becomes the default workspace location. On a fresh Web UI, add and select that directory if no workspace has been selected yet.

Common variants:

# Use another port
npx @deepseek-ai/dsh web --port 8080

# Run a one-off headless task using the same models and credentials
npx @deepseek-ai/dsh --profile headless "Summarize the README"

If the CLI is already installed:

dsh web
dsh --help
dsh web --help

Tip: The web and headless profiles are created automatically under $DSH_HOME (default: ~/.dsh) the first time they are used. You do not need to clone the DeepSeek Harness repository to use Nbility.

Configure Nbility in the Web UI (recommended)

Nbility is neither the built-in DeepSeek card nor an OpenAI or Anthropic catalog provider. Those built-in entries continue to call their official endpoints. Because Nbility is an OpenAI-compatible gateway, add it as a custom provider.

Official reference: Configure models.

Step 1: Open Settings → Models

Open Settings → Models in the Web UI.

Step 2: Add a custom provider

Select Add a custom provider and enter:

Field	Value
Provider ID	`nbility` (lowercase and permanent; sessions, defaults, and credential references use it)
Display name	`Nbility`
Base URL	`https://api.nbility.ai/v1`
API protocol	`openai-completions`
API key	Your Nbility key from the Tokens page

Warning: A Provider ID cannot be renamed after it is saved. Requests, saved sessions, default models, and credential references all use it. To use a different ID, add a new provider and delete the old one.

Step 3: Fetch or enter models

Under Model catalog, select Fetch available models. Harness uses the key shown in the form to call Nbility's OpenAI-compatible GET /v1/models endpoint. Select the models you need, then save the provider.

If discovery fails, enter model IDs manually. Use the live Nbility model catalog or pricing page as the source of truth. Examples:

claude-sonnet-4-6
claude-opus-4-6
gpt-5.4
google/gemini-3-flash
deepseek/deepseek-v4-pro
grok-4.6

Info: The page does not store the literal API key in settings.yaml. Credentials are write-only and stored in $DSH_HOME/.credentials.yaml; settings retain only a reference such as NBILITY_API_KEY.

Step 4: Select a model

After saving, Nbility appears in the model picker at the lower-right of the composer. Selecting a model also makes it the default for new sessions. A session that has already sent a request retains the model recorded in its log.

The picker lists built-in DeepSeek models separately from the custom Nbility provider. Select Claude, GPT, Gemini, and the rest of the Nbility catalog from the Nbility group.

Configure Nbility in `settings.yaml`

You can also declare the same provider directly in $DSH_HOME/settings.yaml (usually ~/.dsh/settings.yaml). Do not put the API key in this file.

llm-pi-ai:
  providers:
    nbility:
      displayName: Nbility
      apiKeyEnv: NBILITY_API_KEY
      api: openai-completions
      baseURL: https://api.nbility.ai/v1
      models:
        - id: claude-sonnet-4-6
        - id: claude-opus-4-6
        - id: claude-opus-4-6-thinking
        - id: gpt-5.4
        - id: google/gemini-3-flash
        - id: deepseek/deepseek-v4-pro
        - id: grok-4.6
        - id: kimi-k2.6
        - id: minimax-m2.7

agent-default-model:
  provider: nbility
  model: claude-sonnet-4-6

Then store the key in any of the following locations. Harness uses the first effective value in precedence order.

Launch environment:

NBILITY_API_KEY=sk-... npx @deepseek-ai/dsh web

$DSH_HOME/.credentials.yaml (the location written by the Models page):

NBILITY_API_KEY: sk-your-nbility-api-key

You can also use a project .env in the launch directory or $DSH_HOME/.env:

NBILITY_API_KEY=sk-your-nbility-api-key

Credential precedence is: process environment → $DSH_HOME/.credentials.yaml → project .env → $DSH_HOME/.env. A key saved through the Models page overrides an older .env value, while a variable passed explicitly to the launching process remains highest priority.

On POSIX systems, .credentials.yaml must have mode 600 or Harness will refuse to read it. Harness applies the correct permissions when the Models page creates the file.

A custom route that is not present in the installed catalog must define api, baseURL, and a non-empty models list. The list becomes the full catalog for that route, so every model that should appear in the picker must be included. An entry containing only id is sufficient.

Vision models

A manually entered model is treated as text-only until it declares otherwise. Harness rejects an attached image before sending the request if the selected model has not declared image input.

For Nbility models that accept images, add input to the corresponding model in settings.yaml:

llm-pi-ai:
  providers:
    nbility:
      apiKeyEnv: NBILITY_API_KEY
      api: openai-completions
      baseURL: https://api.nbility.ai/v1
      models:
        - id: claude-sonnet-4-6
        - id: gemini-3-pro-image-preview
          input: [text, image]
        - id: gpt-image-2
          input: [text, image]

If every manually listed model accepts images, set the route fallback once:

defaultInput: [text, image]

defaultInput is a fallback, not an override, and defaults to [text].

Verify the setup

Open http://127.0.0.1:3080.
Confirm that the model picker contains Nbility and the models you added.
Send a short prompt such as Hi.

You can also query Nbility's model list directly:

curl -H "Authorization: Bearer sk-your-nbility-api-key" \
  https://api.nbility.ai/v1/models

If an ID is missing from the picker, add it to the provider's models list or run Fetch available models again.

Headless and CLI usage

The Web UI and dsh --profile headless share $DSH_HOME. Configure Nbility once, then run:

npx @deepseek-ai/dsh --profile headless "List the files in this directory"

Launcher flags must come first. The first token the launcher does not recognize, and everything after it, is passed to the selected profile:

dsh --profile web --port 8080
dsh --profile web --help
dsh --help

Troubleshooting

`MISSING_CREDENTIAL`

The route references NBILITY_API_KEY, but no effective value was found. Save the key under Settings → Models or set the environment variable in the shell that launches dsh.

`UNKNOWN_MODEL`

The selected model is not in the provider's models list. Fetch models again or add the ID manually. Nbility's available IDs can change over time, so verify the current value in the model catalog.

Model discovery or conversations return 401

Verify the key in the Nbility console.
The base URL must be https://api.nbility.ai/v1, including /v1.
Do not paste the key into settings.yaml; use the credentials file or an environment variable.

Requests still go to DeepSeek or OpenAI

You may have configured the built-in DeepSeek card or an OpenAI / Anthropic catalog provider. Those providers continue to use their official endpoints. Delete the incorrect entry and add a custom provider with Provider ID nbility and base URL https://api.nbility.ai/v1.

Images are rejected before sending

The selected model does not declare image input. Add input: [text, image] as shown under Vision models, then start a new session. An already attached image remains in the old session log.

Configuration changes do not take effect

Provider and credential-file changes apply to the next request and generally do not require a restart. Existing sessions retain the model recorded in their logs, so start a new session after changing the default. If the key comes from the launching process environment, restart dsh after changing it.

File locations

Path	Purpose
`$DSH_HOME/settings.yaml`	Providers, model lists, and the default model; usually `~/.dsh/settings.yaml`
`$DSH_HOME/.credentials.yaml`	API keys only
`$DSH_HOME/profiles/web/`	The automatically created `web` profile

Security notes

Prefer saving keys through the Models page. Keep only the apiKeyEnv reference in settings.yaml.
Do not start Harness in a directory that contains sensitive files you do not want the agent to read.
For advanced timeout, retry, and reasoning compatibility fields, see the official dsh-llm-pi-ai README.