Preface

When developing agents with DeepSeek Harness (DSH), agents often start background services (such as databases and API services). These processes are usually launched via shell commands or Start-Process, making it difficult for developers to intuitively see in the Web GUI “which conversation started which services,” and they cannot quickly view logs or perform start/stop operations.

The dsh-process-board plugin solves this issue. It is a DSH service panel plugin that allows you to view service ownership, manage start/stop actions, view logs in real time, and replay startup parameters from the Web GUI sidebar.

Core Capabilities

This plugin provides the following features:

  • Session ownership: It uses the DSH_SESSION_ID environment variable injected by the DSH host, combined with process tree lineage, to attribute each service to the conversation that started it. The panel groups services by the Chinese title of the session.
  • Service view: Built-in filtering logic is applied (port/log marker gate, removing npm/cross-env launcher shells, and merging nginx master-worker processes) to display only real service processes and avoid log flooding.
  • Three-state probing: It displays three states:
    • running: The port is in a listening state.
    • pid-alive: The process exists but the port is not listening (e.g., Java cold-start phase).
    • stopped: The process has ended.
    • It supports checking the service’s response code via HTTP probing.
  • Start/stop management: When stopping a service, it uses graceful termination (SIGTERM/taskkill), waits for a grace period, then force-kills the process tree. When the service state is stopped, a Start button appears inline, allowing replay of the registered startup parameters.
  • Log viewing: At startup, it injects the DSH_PB_LOG environment marker. The panel uses a split-pane design and tails the log stream in real time. It supports red highlighting for ERROR and yellow highlighting for WARN, refreshes automatically every 4 seconds, and supports sticky bottom scrolling.
  • Fullscreen mode: The panel ⛶ fills the viewport; the log ⛶ covers the entire panel. Press Esc to exit level by level (log fullscreen → panel fullscreen → close).

Installation and Enablement

The prerequisite is that DSH is already installed (the dsh command is available).

Install the plugin using the following command:

dsh plugin --profile web add dsh-process-board

After installation, you must restart the DSH host (run dsh web again) and refresh the page in your browser. A Process Panel entry will appear in the sidebar.

Typical Usage

To make the panel correctly display services and logs, the services need to be started properly.

1. Start with a log marker (Shell/Bash)
When starting the service, specify the log file using the environment variable DSH_PB_LOG, and redirect standard output to that file.

export DSH_PB_LOG=/tmp/my-service.log
java -jar app.jar >> /tmp/my-service.log 2>&1 &

2. Explicitly register and start via API
If more fine-grained control is needed, you can explicitly register the service information (name, startup arguments, working directory, port, log file) via the API. Afterward, the panel can directly click the Start button to replay the command.

curl -X POST http://127.0.0.1:3080/api/plugins/process-board/start \
  -H 'content-type: application/json' \
  -d '{"name":"my-svc","argv":["java","-jar","app.jar"],"cwd":"/path/to/app","port":8080,"logFile":"/tmp/my-svc.log"}'

3. Start via PowerShell
In Windows PowerShell, you can use Start-Process with redirection.

$env:DSH_PB_LOG = "$env:TEMP\my-service.log"
Start-Process java -ArgumentList '-jar','app.jar' -RedirectStandardOutput $env:DSH_PB_LOG -WindowStyle Hidden

Notes

  • Limitation on Mac: In the current version, after installation on Mac, the plugin can load, but the scanner returns an empty result. This is because scanner.js contains an early-return logic where process.platform !== 'win32'. The probing and stopping layers are ready for cross-platform use, but process scanning is not yet active on Mac.
  • Installation path limitation: When installing using the link: method, only local directory paths are accepted. For example, dsh plugin --profile web add link:~/dsh-process-board is valid, while link:https://... will fail to resolve.
  • Runtime dependencies: The plugin client is implemented with pure DOM and has zero runtime dependencies.

Conclusion

dsh-process-board is a practical tool for DSH developers. By using environment variables and process tree analysis, it visualizes and standardizes service ownership. For agent development scenarios that require frequent management of background services, it can significantly improve debugging and operations efficiency.

GitHub repository