Guides

Use AI Hub with DeepSeek Harness

Run DeepSeek Harness headless agent sessions through AI Hub's OpenAI-compatible Chat Completions endpoint with a Cordis provider patch.

@deepseek-ai/dsh@0.2.2-rc.1 is a release-candidate package and requires Node.js 24.9.0 or later. Pin the tested version when installing, and scope unattended runs to --profile headless over https://tokenhub-api.belive.sg/api/v1.

1. Prepare your workspace and key

Create a dedicated workspace inference key in API keys in this AI Hub environment and set a monthly spend cap. Use the API base below with a key from the same environment.

Supply the secret as BELIVE_TOKENHUB_API_KEY in the shell environment or in $DSH_HOME/.env (by default ~/.deepseek-harness/.env):

bash
printf 'AI Hub API key: '
read -r -s BELIVE_TOKENHUB_API_KEY
printf '\n'
export BELIVE_TOKENHUB_API_KEY
  • Do not store an AI Hub key in DEEPSEEK_API_KEY. When DEEPSEEK_API_KEY is present, DeepSeek Harness mounts its dsh-web-search-deepseek plugin and sends web-search calls with that token directly to api.deepseek.com instead of AI Hub.
  • Headless runs ignore .credentials.yaml. --profile headless disables the interactive dsh-credentials store, so keys saved for interactive sessions are not loaded unless exported in the process environment or $DSH_HOME/.env.

2. Install the pinned CLI

Verify that Node.js 24.9.0 or later is active, then install the pinned CLI release candidate:

bash
node --version
npm install -g @deepseek-ai/dsh@0.2.2-rc.1
dsh --version

3. Configure $DSH_HOME/cordis.patch.yml

Create ~/.deepseek-harness/cordis.patch.yml (or $DSH_HOME/cordis.patch.yml when DSH_HOME is customized) to configure llm-pi-ai and agent-default-model:

yaml
- id: llm-pi-ai
  config:
    providers:
      belive-aihub:
        displayName: BeLive AI Hub
        apiKeyEnv: BELIVE_TOKENHUB_API_KEY
        api: openai-completions
        baseURL: "https://tokenhub-api.belive.sg/api/v1"
        compat:
          supportsDeveloperRole: false
        models:
          - id: qwen/qwen3.8-flash
            name: Qwen3.8 Flash
            contextWindow: 1000000
            maxTokens: 32768
            input: [text, image]
            compat:
              thinkingFormat: qwen
              supportsReasoningEffort: false
            reasoningEfforts:
              high: high
              off:
          - id: qwen/qwen3.8-max
            name: Qwen3.8 Max
            contextWindow: 1000000
            maxTokens: 32768
            input: [text, image]
            compat:
              thinkingFormat: qwen
              supportsReasoningEffort: false
            reasoningEfforts:
              high: high
              off:
          - id: deepseek/deepseek-v4.1-flash-1017
            name: DeepSeek V4.1 Flash
            contextWindow: 1024000
            maxTokens: 32768
            input: [text, image]
            reasoningEfforts:
              minimal: minimal
              low: low
              medium: medium
              high: high
              xhigh: xhigh
              max: max
              off: none

- id: agent-default-model
  config:
    provider: belive-aihub
    model: qwen/qwen3.8-flash
    reasoningEffort: high
  • Exact catalogue IDs: Every id under models is an exact author/slug ID from Models. agent-default-model pairs provider: belive-aihub with that exact model ID and dispatches requests to https://tokenhub-api.belive.sg/api/v1/chat/completions.
  • Bounded maxTokens: qwen/qwen3.8-flash and qwen/qwen3.8-max publish a 131000-token completion limit and deepseek/deepseek-v4.1-flash-1017 publishes 384000. Setting maxTokens: 32768 bounds each turn's output reservation while leaving room for reasoning and multi-file edits. Check https://tokenhub-api.belive.sg/api/v1/models or Models before adding other models.
  • Thinking controls (thinkingFormat and reasoningEfforts):
    • On qwen/qwen3.8-flash and qwen/qwen3.8-max, thinkingFormat: qwen with supportsReasoningEffort: false toggles DashScope's binary enable_thinking: true or false parameter (off: omits the effort so pi-ai sends enable_thinking: false). DashScope accepts top-level reasoning_effort without error, whereas the catalogue publishes enable_thinking and thinking_budget.
    • On deepseek/deepseek-v4.1-flash-1017, dsh-llm-pi-ai defaults to OpenAI-style reasoning_effort. Values minimal through max are accepted by the upstream route, and off: none maps reasoningEffort: off to reasoning_effort: "none", which disables thinking (omitting reasoning_effort leaves thinking enabled by default).
  • supportsDeveloperRole: false: Rewrites system prompts from OpenAI's developer role to system on the client side. This flag is optional: AI Hub accepts the developer role on Qwen routes and sends it as system. Keeping it is harmless.

4. Run a headless task

Verify the composed configuration, then run a bounded one-shot task in a disposable project directory:

bash
dsh --profile headless --dump-config >/dev/null
dsh --profile headless --approval-policy never \
  "Read package.json and list its script names."

Switch models or disable thinking on a single invocation with a --patch overlay:

bash
cat > deepseek.patch.yml <<'EOF'
- id: agent-default-model
  config:
    provider: belive-aihub
    model: deepseek/deepseek-v4.1-flash-1017
    reasoningEffort: off
EOF

dsh --profile headless --patch ./deepseek.patch.yml --approval-policy never \
  "Run node -v with bash and report the version."

In --profile headless, read-only file inspection is pre-approved while shell commands (bash) and file edits wait for interactive confirmation unless --approval-policy never is set. Use --approval-policy never only inside an isolated checkout or container.

This guide covers --profile headless over Chat Completions (https://tokenhub-api.belive.sg/api/v1). Check Activity after a run to inspect the req_… request ID, token usage and recorded cost.

Troubleshooting

  • 401 authentication error: Confirm BELIVE_TOKENHUB_API_KEY is exported to the dsh process or written to $DSH_HOME/.env, and matches this AI Hub environment. Never print the secret to inspect it.
  • Raw <function=…> text during streaming tool turns on qwen/qwen3-coder-flash: Use qwen/qwen3.8-flash or qwen/qwen3.8-max for streaming agent tool loops until a later AI Hub release fixes this.