Introduction

One of the core design principles of DeepSeek Harness (DSH) is “everything is a plugin”. Through plugins, users can extend model sources. Nous Portal provides a free model tier that includes Hy3, Ox Alpha, and others. The jiesou/dsh-nous-portal-free-provider plugin integrates the free tier of Nous Portal into the web profile of DSH and uses these models through an OAuth device code login flow.

Core Features

This plugin implements the following features:

  • OAuth Device Code Login: completes authorization login through a standalone CLI.
  • Dynamic Model Discovery: fetches the model list from the upstream /v1/models endpoint at startup, filters out models priced at $0 as the catalog, and does not hard-code IDs.
  • Reasoning Effort Support: exposes the levels supported by the upstream, does not send the field by default, and provides an Off switch.
  • Image Offload Mechanism: when an image exceeds the configured size, it triggers IMAGE_OFFLOAD_REQUIRED; DSH stores the oldest image in image/offload and retries.
  • Refresh Token Rotation: supports single-use Refresh Tokens and ensures concurrency safety through a modifyRecord lock mechanism.

Installation and Enablement

Install the plugin by running the following command in the terminal:

dsh plugin --profile web add @jiesou/dsh-nous-portal-free-provider

After installation, run the bundled CLI of the plugin to log in:

node ~/.dsh/profiles/web/node_modules/@jiesou/dsh-nous-portal-free-provider/lib/cli.js

During login, follow the terminal prompts to log in with the device code. A running dsh instance will hot-load the plugin, so no restart is required.

CLI Options

The login CLI supports the following options to override the default configuration:

--portal-url <url>       Portal 地址（默认 https://portal.nousresearch.com）
--client-id <id>         OAuth client id（默认 hermes-cli）
--scope <scope>          申请的 scope（默认 inference:invoke）
--dsh-home <dir>         凭据文档所在 home（默认 $DSH_HOME 或 ~/.dsh）
--path <file>            凭据文档完整路径，优先于 --dsh-home

Configuration and Mechanism

The plugin uses the unified ctx.credentials interface to manage credentials. The storage structure supports two sources: regular API Keys and OAuth Grants.

The plugin provides the following Settings configuration items:

  • retryPolicy: the retry policy for model requests; default is always (retry on every failure).
  • maxRequestImageBytes: the limit for base64 images inlined in a single request; default is 2097152 (2 MiB).
  • requestImageMaxBytes: the limit after re-encoding a single image; default is 1048576 (1 MiB).

Notes

  1. Dependency Version: DSH version >=0.2.0-rc.2 is required.
  2. Single-Use Token: Each time the Portal Refresh Token is refreshed, a new Token is generated and the old Token is immediately invalidated. If a used old Token is submitted again, the server may determine that the token has been stolen and revoke the entire session. Therefore, the plugin uses a lock mechanism when refreshing Tokens. If you see the Refresh token reuse detected prompt, you need to log in again using the steps above.
  3. UI Rendering Bug: The Portal-side device code approval page once had a rendering bug (Issue #47950). If authorization gets stuck, first confirm that the browser is logged in to the Portal, then retry.
  4. Protocol Change: The Portal has retired the legacy mint endpoint, and this plugin has been adapted to the login flow of the newer hermes-cli.

Conclusion

This plugin provides DSH users with a way to access free models on Nous Portal. For more details and source code, refer to:

  • GitHub: https://github.com/jiesou/dsh-nous-portal-free-provider
  • Catalog page: https://www.skillhub.cn/plugins/jiesou/dsh-nous-portal-free-provider