Preface

DeepSeek Harness (DSH) adopts a plugin-based architecture. In remote deployment or proxy access, developers usually need to handle separately the security Origin of remote settings and an independent password access gateway. If they are not distinguished, it can easily lead to confused permission verification or unclear security boundaries.

The lemoncat7/dsh-remote-settings-compat plugin aims to consolidate these two capabilities into a single installation package. Through a unified configuration entry point, it provides trusted browser Origin management, an independent password gateway, and anonymous Knowledge sharing functionality, while remaining decoupled from the DSH main program.

Plugin Positioning

This is a unified remote access compatibility plugin for DeepSeek Harness, maintained by developer lemoncat7. It does not modify the DSH main program, nor does it take over Knowledge or SSH business routes. Instead, it provides extension capabilities through the official Bundle interface.

Core Features

The plugin mainly includes the following capabilities:

  • Trusted browser Origin management: Allows explicitly specified browser Origins to use DSH’s official models, credentials, and plugin settings. This is the authoritative source for Origins and is also used for remote settings and password gate validation.
  • Independent password gateway: Provides a transparent proxy from port 3081 to 3080. Passwords are stored irreversibly using scrypt, and browsers use HttpOnly, SameSite session cookies.
  • Security policy: Includes login rate limiting, session expiration, optional IP binding, and one-click revocation of all sessions.
  • Machine API compatibility: Configured machine APIs (such as /knowledge-api/v1) can continue to use Bearer Tokens, and the Tokens are verified by the target plugin.
  • Anonymous Knowledge sharing: Anonymous reading of Knowledge can be explicitly enabled. Only valid shared pages, manifests, and content GET requests in the form of /knowledge-api/v1/shared/share_... are allowed, without exposing search, write-back, or management interfaces.

Installation

Install in a Node.js environment:

npm install

Environment requirements: The Node.js version must be ^22.19.0 or >=24.0.0.

Typical Usage

Docker Deployment Configuration

Configure port mappings in docker-compose.yml. Port 3081 is the password gateway entry point, and 3080 is the native DSH service.

services:
  dsh:
    ports:
      # 仅允许回环访问，或根据网络环境调整
      - "127.0.0.1:3080:3080"
      # 密码网关，同机 Nginx 时可绑定 127.0.0.1
      - "127.0.0.1:3081:3081"

Plugin internal configuration example:

dsh-access-gate:
  enabled: true
  listenHost: 0.0.0.0
  listenPort: 3081
  secureCookies: true

remote-settings-compat:
  trustedOrigins:
    - https://dsh.example.com:2439

Nginx Reverse Proxy Configuration

Nginx must proxy all traffic to 3081 and strictly preserve the Host header.

location / {
    proxy_pass http://127.0.0.1:3081;

    # 必须保留非默认端口；不能用 $host
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Port $server_port;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $http_connection;
    proxy_http_version 1.1;
}

Initial Enablement Flow

The enablement process is divided into seven stages to avoid access interruption caused by improper configuration:

  1. Fill in the complete trustedOrigins under “Settings → Plugins → Remote Access”.

  2. Enable the gateway and save the listen address, port, and Cookie policy (such as secureCookies: true).

  3. Use the one-time initialization token in the DSH startup log to set the password.

  4. Expose port 3081, restart DSH, and first confirm that port 3081 can open the login page.

  5. Switch the reverse proxy as a whole from 3080 to 3081.

  6. Open “Deployment Self-Check” and confirm that Host, Origin, current entry point, and Credentials are all normal.

  7. Finally, remove the external exposure of 3080, or restrict it to the host machine’s loopback address.

Upgrade and Compatibility

When upgrading from the standalone dsh-access-gate, the plugin will continue to read the old settings namespace and credential records, so there is no need to reset the password or publish the Origin again. However, after the new package takes effect, the old dsh-access-gate bundle must be removed from the profile to avoid two gateways listening on the same port at the same time.

Considerations

  • Configuration separation: Configuring trustedOrigins does not automatically enable 3081 or the password functionality; they must be configured separately.
  • Nginx rules: Using the $host variable is strictly prohibited. You must use $http_host to preserve non-default ports.
  • Credentials permissions: When using the official local Provider, the password file is recommended to have 600 permissions, avoiding it being read by other processes.
  • Business routes: The plugin does not take over Knowledge or SSH business routes; these functions are still handled by DSH’s native plugins.

Conclusion

This plugin manages the security policy for remote access through a unified entry point, providing developers with an integrated solution from Origin validation to the password gateway. Before using it, please confirm the Node.js version and carefully check the Nginx configuration to avoid security issues caused by loss of the Host header.

Project address: https://github.com/lemoncat7/dsh-remote-settings-compat