Introduction

In DSH’s plugin ecosystem, many capabilities are already running via the Web UI and the host process. However, third-party scripts, command-line tools, browser-based services, or other clients often still require a stable HTTP channel. dsh-api-gateway is a DSH plugin designed for this scenario: it exposes the running DeepSeek Harness as an HTTP API, allowing external clients to create sessions, send messages, and receive streaming replies via SSE.

This plugin is maintained by litestartup-com and is licensed under MIT. It does not provide an independent inference service but rather an HTTP access layer surrounding the current DSH session and agent.

What is this

dsh-api-gateway is a DeepSeek Harness plugin designed to provide a simple REST + SSE interface for arbitrary third-party clients.

The main problems it solves are:

  • Existing DSH sessions and agent capabilities exist, but external programs cannot call them directly.
  • Need to expose sessions created in the Web UI to scripts or services.
  • Need to read replies in a streaming manner, rather than just waiting for the final result.
  • Need to distinguish visible answers from model reasoning content.
  • Need to publish gateway events to the host event bus for easy integration by other plugins.

Core Features

The capabilities listed below are derived from the plugin documentation and verified facts.

  • Expose the running DeepSeek Harness as an HTTP API, allowing third-party clients to create sessions and receive replies in a streaming manner.
  • Provide a REST + SSE interface; the README explicitly lists 10 endpoints and supports assistant/chunk token-level streaming output.
  • Support API-key authentication, as well as status, toggle, and key rotation in the GUI settings card.
  • API sessions enter the real workspace and are grouped in the sidebar.
  • Support session discovery, read-only access to any session history, and takeover of GUI sessions to continue driving them.
  • Return the visible answer text separately from the reasoning reasoning.
  • Publish the following events on the Cordis event bus:
  • gateway/session-created
  • gateway/session-released
  • gateway/message
  • gateway/turn-end
  • Support Linux, macOS, Windows clients, including PowerShell; the server is tolerant of GBK.

Installation and Enablement

package.json requires Node >=20. Before installing, it is recommended to check the source code and the MIT license. The plugin runs in the DSH host process and accesses session and workspace contexts available to the current process, so it is best to confirm you trust the source of this code before installing.

Install from GitHub

Below is the official installation command:

dsh plugin --profile web add github:litestartup-com/dsh-api-gateway

This installation method does not require additional build approval, as lib/ is committed. The build script only runs during the prepack phase of packing/publishing.

Install from a local tarball

If you have already downloaded or packaged the plugin files, you can also install using a local file:

dsh plugin --profile web add ./dsh-api-gateway-0.1.0.tgz

Uninstall

If you are sure you no longer need it, you can remove it with the following command:

dsh plugin --profile web remove dsh-api-gateway

Typical Usage

First, ensure DSH is running and the plugin is loaded. Then use the example script to initiate a question:

./examples/ask.py "introduce yourself"

In Windows PowerShell, you can use:

.\examples\ask.ps1 "introduce yourself"

These two example commands have the same goal: send a prompt to the local gateway and receive a reply.

If you want to see the underlying HTTP calls directly, you can execute them in the following order. First, declare the gateway base address:

BASE=http://127.0.0.1:3080/api-gw/v1

POST /key is used for bootstrapping to get the API key. According to the README, it closes after the first call, and subsequent calls should use the generated key.

KEY=$(curl -s -X POST $BASE/key | jq -r .apiKey)

Create a session:

SID=$(curl -s -X POST $BASE/sessions -H "Authorization: Bearer $KEY" | jq -r .sessionId)

First, hook up the SSE stream:

curl -sN $BASE/sessions/$SID/stream -H "Authorization: Bearer $KEY" &

Then send a message:

curl -s -X POST $BASE/sessions/$SID/messages -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"content":"hello"}'

The order here is quite important: hook up the stream first, then send the message. The streaming output is returned via SSE, and the message sending interface is responsible for submitting the content to the session.

Session, Concurrency, and Management Notes

When using the gateway, there are a few configurations and behaviors related to the session lifecycle that need attention.

  • maxSessions limits the number of concurrent sessions; creating fails when the limit is reached.
  • DELETE /sessions/:id releases maxSessions slots and ends the session’s SSE stream, but retains history.
  • When taking over co-driven GUI sessions, the GUI’s agent is not disposed, and the Web UI retains the session.
  • The adminKey example value is change-me, used to enable admin endpoints and card controls.
  • The API key is obtained via POST /key bootstrap; the README states it closes after the first call.

For clients that create sessions based on tasks, releasing session slots promptly is more critical than simply deleting messages. Otherwise, once concurrency reaches the limit, subsequent session creation will be affected.

Use Cases

This plugin is suitable for the following usage scenarios:

  • Drive DSH agents via command-line scripts.
  • Allow Python, Shell, PowerShell, or other clients to access existing DSH sessions.
  • Save session context on the server and continue appending messages to the same session.
  • Read-only retrieval of a session’s history for logging, auditing, or secondary processing.
  • Integrate gateway events into other host plugins.
  • Need to distinguish text and reasoning in the returned results.

It is more suitable for integrating into an existing DSH runtime environment rather than deploying a complete agent platform separately. Before use, you should still check the source code, license, and the gateway’s exposed surface, especially configurations such as API key, admin key, concurrency limits, and CORS.

Related Links

  • Directory page: https://www.skillhub.cn/plugins/litestartup-com/dsh-api-gateway
  • GitHub: https://github.com/litestartup-com/dsh-api-gateway