The core design philosophy of DeepSeek Harness is “Everything is a Plugin.” When developing or debugging an Agent, the runtime reasoning process and tool-call details are often scattered across multiple log files and are difficult to review in a centralized way. dsh-plugin-log-forwarder, as a plugin, is designed to forward all Agent runtime events in real time to external logging systems (WebSocket, Loki, or local files) for debugging, monitoring, and demonstrations.

Feature Overview

The plugin provides the following capabilities:

  • Full-event capture: Subscribes to Harness session event streams (session/created, session/event, session/disposed, agent/error) and normalizes them into unified JSON.
  • Three parallel output channels: The WebSocket, Loki, and local file channels are independent of one another and can all be enabled simultaneously.
  • Event filtering: Filters events using an includeEventTypes allowlist and an excludeEventTypes blocklist.
  • Sensitive information redaction: Redacts fields such as api_key, password, token, and secret by default.
  • Pause/Resume: Supports globally pausing forwarding (while keeping the WebSocket Server online). It can be controlled via Agent tools or the panel.
  • Channel monitoring: Displays runtime status and forwarded/failed/dropped statistics in real time.
  • Bypass design: Read-only forwarding that does not interfere with Agent execution; cleanly closes connections and buffers on uninstall.

Installation and Configuration

Prerequisites

  • DeepSeek Harness is installed and running (desktop edition or headless).
  • Node.js ≥ 20 (required for building).

Install Plugin

Use the official plugin management command to install it:

dsh plugin --profile desktop add dsh-plugin-log-forwarder

After installation, restart DSH to load the configuration.

Enable and Configure Channels

Edit the profile’s patch configuration (usually ~/.dsh/profiles/desktop/cordis.patch.yml) and append the following configuration to the - insert: list. This configuration is merged into the default configuration, and multiple channels can be enabled at the same time.

- insert:
    - id: log-forwarder
      name: dsh-plugin-log-forwarder
      config:
        enable: true          # 插件总开关
        autoStart: true       # 加载后立即开始转发
        channels:
          websocket:
            enable: true      # WebSocket 通道
            port: 18765       # 绑定 127.0.0.1；被占用自动尝试 +1（最多 5 次）
          file:
            enable: false     # 本地文件通道
            path: ''          # 路径模板；留空使用默认，建议用 {sessionId}.l 避免双重前缀
          loki:
            enable: false     # Loki 通道
            url: 'http://localhost:3100'
            tenantId: ''      # 多租户时必填（X-Scope-OrgID）
            token: ''         # 可选，Bearer Token
            bufferSize: 1000  # 内存缓冲上限
        filter:
          includeEventTypes: []   # 白名单，空 = 全部
          excludeEventTypes: []
        redaction:
          enable: true
          sensitiveFields: [api_key, apikey, password, token, secret, authorization]

Usage

WebSocket Real-Time Monitoring

After restarting DSH, the WebSocket channel is enabled by default.

  1. Browser verification: Open the built-in status page to view the real-time event stream.
    start http://127.0.0.1:18765/
  1. Command-line verification: Use wscat to observe events in real time.
    npx wscat -c ws://127.0.0.1:18765

Local File Archival

After enabling the file channel, events are written into JSONL files by session. For the path template, it is recommended to use {sessionId}.l directly to avoid a double prefix caused by the auto-generated session- prefix.

After enabling the loki channel, the plugin pushes logs to Loki. Use the source label when querying.

{source="dsh-log-forwarder"}

Agent Tool Control

The plugin registers 4 tools for the Agent and can be controlled via natural language:

  • log_forwarder_status: View global status and statistics.
  • log_forwarder_channel_status: View details for a single channel.
  • log_forwarder_pause: Pause forwarding.
  • log_forwarder_resume: Resume forwarding (also reconnects disconnected Loki).

Notes

  1. Configuration effectiveness: Configuration takes effect only when the plugin is loaded; restart DSH after changes.
  2. Loki disconnection handling: After the Loki channel disconnects, manual recovery is required (using the above tool or Agent commands). By default, the plugin stops retrying after 10 consecutive failures.
  3. Permissions: The plugin runs with the current DSH process permissions. Ensure it has write access to the configured log paths and the Loki target.
  4. Ecosystem note: This plugin is maintained by community developers and is not affiliated with the official DeepSeek organization.

Plugin directory page and source code address:
https://www.skillhub.cn/plugins/zhaoxuejie/dsh-plugin-log-forwarder
https://github.com/zhaoxuejie/dsh-plugin-log-forwarder