Introduction

DeepSeek Harness (DSH) is a plugin-based architecture. When running the DSH process locally, remote control via smartphone is a common need. The dsh-telegram-control plugin runs a Telegram Bot inside the DSH process, communicates with the Telegram Bot API through long polling, and allows users to send messages via Telegram to control agents, manage sessions, and background tasks.

Plugin Overview

dsh-telegram-control is a client-side plugin for DeepSeek Harness maintained by jackControls. It integrates a Telegram Bot into the Harness process, enabling remote interaction through / commands and inline buttons. The plugin does not depend on an external runtime and runs only as a Cordis function plugin, requiring coordination with DSH core dependencies.

Core Features

The plugin provides the following core capabilities:

  • Remote agent control: Plain-text messages are sent as follow-ups to the selected session, and replies (including thinking blocks 💭) are returned through Telegram in real time.
  • Command interface: Check status and manage resources with commands such as /status, /agents, and /jobs.
  • Mobile approval: Harness permission requests (such as sandbox escalation) are delivered through Telegram, with ✅ Allow once / ❌ Reject inline buttons for approval.
  • Automatic command menu completion: The Bot registers commands via setMyCommands and supports autocomplete while typing.
  • Real-time session streaming: Use the /watch command to push real-time output from a specified session to the chat window.
  • Whitelist-based authentication: Only chat IDs in the configured list are allowed access; unknown chats only see a prompt.
  • Output safety: All dynamic text is HTML-escaped before sending to prevent injection.

Installation and Enablement

Before installing, ensure the environment meets the following requirements:
* Node.js version >= 22
* DSH is installed and running
* You have a valid Telegram Bot Token (obtainable via @BotFather)

Run the following command to install the plugin:

dsh plugin --profile web add github:jackControls/dsh-telegram-control

After installation, configure environment variables in the process where DSH is running:

export DSH_TELEGRAM_TOKEN='123456:ABC-DEF...'
export DSH_TELEGRAM_ALLOWED_CHATS='123456789,987654321'

Restart the DSH process, send a private message to the Bot with /help, and you can start using it.

Command Usage

The plugin provides the following commands for interaction:

  • /help or /start: Display the command list.
  • /status: View running status, number of sessions, and number of background tasks.
  • /agents: List all sessions (including running and paused sessions), showing status, model, and current selection marker.
  • /agent <number>: Select a session by number.
  • /agent <name>: Select a session by a substring of its title or ID.
  • /agent <session id>: Select by exact session ID.
  • /jobs: List background tasks.
  • /kill <job id>: Stop the specified background task.
  • /cancel: Cancel the current turn of the currently selected session.
  • /watch / /unwatch: Turn real-time output streaming on or off.
  • /chatid: Get the ID of the current chat (for configuring the whitelist).

Configuration Options

In addition to environment variables, the plugin supports the following configuration options (can be set in code or fall back to environment variables):

Configuration option Environment variable fallback Default Description
token DSH_TELEGRAM_TOKEN Required Telegram Bot Token.
allowedChatIds DSH_TELEGRAM_ALLOWED_CHATS [] List of allowed chat IDs; an empty list rejects everyone.
apiBase — https://api.telegram.org Bot API base address.
defaultAgentId — None Target session ID to which messages are sent by default when no session is selected.
pollTimeoutSec — 50 Long polling timeout (seconds).
replyTimeoutMs — 600000 Maximum timeout for waiting for an agent reply (milliseconds).
showToolCalls — false Whether to display tool-call notifications while waiting for a reply.
maxMessageChars — 4000 Maximum characters per message; longer messages are automatically split.

Notes

  1. Security policy: The plugin uses a whitelist mechanism; if allowedChatIds is empty, all requests are rejected. Be sure to add trusted chat IDs to the configuration.
  2. Output processing: All dynamic text is HTML-escaped before sending to ensure safety.
  3. Session management: Paused sessions are automatically resumed when a message is sent for the first time, preserving the original session preset and history.
  4. Dependency requirements: Node.js >= 22 is required, and the DSH process must have network access to the Telegram API.

Summary

dsh-telegram-control addresses the need to remotely control DeepSeek Harness sessions and tasks from mobile devices. Through simple commands and inline button interactions, developers can manage complex Agent workflows and background tasks on their phones. The plugin code is open source and can be installed directly via dsh plugin, making it suitable for users who need to maintain DSH processes in mobile scenarios.