Foreword

DSH (DeepSeek Harness) adopts a plugin-based architecture, and the ecosystem contains multiple workflow plugins. Developers often need to handle scheduled or background tasks without blocking the current foreground session. autoqueue is a workflow plugin maintained by alin-ever. It is designed to submit Markdown tasks to a queue, where the DSH background automatically dispatches, unblocks, retries, settles, and archives them.

The core design of this plugin is the separation between schedulers and tasks: the scheduler handles timed triggering (such as cron) and automatically creates an immediate task when the scheduled time arrives; an immediate task performs a one-time specific piece of work and has a full state-machine lifecycle. They do not interfere with one another, ensuring that normal tasks do not disturb users and queued tasks do not change the runtime state of ordinary foreground sessions.

Core Features

Based on verified facts, the plugin includes the following core capabilities:

  • Separation of scheduling and execution: The scheduler does not enter the state machine and does not execute; immediate tasks have full state transitions.
  • Timed triggering: Supports setting trigger times with cron expressions or the schedule field.
  • State machine management: Tasks have six states: pending, running, done, failed, stopped, and interrupted.
  • Session isolation and permission control: Each execution uses an independent dedicated session ID and runtime directory, without interfering with normal Host sessions.
  • Unattended execution: The execution mode is strictly restricted, with a default maximum concurrency of 1.
  • React dashboard: Provides a monitoring interface with three independent tabs: Tasks, Scheduling, and Archive.
  • File inbox mechanism: Supports creating tasks by directly dropping Markdown files into the queue directory.
  • Automatic tool injection: After the plugin is loaded, it automatically registers 19 autoqueue_* Host tools with normal Host sessions.
  • HTTP API and OpenAPI: Provides a complete RESTful API and OpenAPI 3.1 documentation access.

Installation and Configuration

Installation

Add the plugin with the official installation command:

dsh plugin --profile web add -w @alintever/dsh-plugin-autoqueue@latest

Compatibility

  • Baseline version: The exact baseline audited and self-tested for the plugin is @deepseek-ai/dsh 0.1.5-rc.1.
  • Manifest range: The plugin manifest accepts >=0.1.1-rc.2 <0.1.6. After upgrading DSH, it is recommended to rerun unit tests and Playwright.
  • Dependencies: @deepseek-ai/dsh-sandbox-policy, @deepseek-ai/dsh-tools, and @deepseek-ai/dsh-user-approval follow the DSH engine version range.

Configuration

For remote deployment or reverse proxy scenarios, authentication parameters must be configured:

config:
  allowedHosts:
    - queue.example.com
  apiToken: "replace-with-a-long-random-secret"

The token can also be provided via environment variables: DSH_AUTOQUEUE_TOKEN or AUTOQUEUE_API_TOKEN. Once a token is set, local access to localhost must also include the authentication header.

Usage

1. Create a Task via API

Use POST /api/queue/task to create an immediate task:

curl -X POST http://127.0.0.1:3080/api/queue/task \
  -H 'Content-Type: application/json' \
  -d '{
    "requestId": "my-001",
    "key": "daily-report",
    "content": "# 生成日报\n\n收集今天的工作数据，输出 report.md",
    "priority": 5,
    "autoArchive": true,
    "enableNotifications": false
  }'

2. Create a Scheduler via API

Include the cron or schedule field in the request body to create a scheduler:

curl -X POST http://127.0.0.1:3080/api/queue/task \
  -H 'Content-Type: application/json' \
  -d '{
    "requestId": "my-002",
    "key": "weekly-insight",
    "content": "# 生成周报\n\n汇总本周代码提交与 issue 进展",
    "cron": "0 9 * * 1",
    "priority": 5
  }'

When the scheduled time arrives, the scheduler automatically creates an immediate task, and the immediate task inherits the scheduler’s configuration.

3. Use the File Inbox

The queue directory is ~/.dsh/queue/tasks/ by default. The file name is used as the key, and the body is used as the task content. File headers support declaring scheduling methods:

echo "# 生成日报" > ~/.dsh/queue/tasks/daily-report.md

Markdown file header example:

<!-- cron: 0 8 * * 1-5 -->
<!-- deadline: 0 21 * * * -->
# 每日工作报告

4. Use the Dashboard

After installation, click “Task Workbench” in the DSH Web sidebar. The dashboard provides three tabs: Tasks, Scheduling, and Archive. It supports operations such as viewing status, editing (when not running), stopping, rerunning, and archiving.

Security and Isolation

autoqueue strictly restricts execution modes to ensure it does not interfere with the main process:

  1. Session isolation: Each attempt uses an independent runtime directory and a dedicated session ID (autoqueue-session-<uuid>). The Runner refuses to read or write sessions outside this namespace.
  2. Execution mode: Uses the autoqueue-unattended-v2 preset, disabling questions, jobs, subagent/fork/control/list, workflow, and Ralph. bash/pwsh enforce enableRunInBackground:false.
  3. Permission pinning: After a session is created, approvalPolicy is pinned to never and persistence validation is performed.
  4. Host tool isolation: The plugin injects 19 autoqueue_* tools into normal Host sessions, but these tools are hidden in its own autoqueue-session-* task agents. The execution-layer Guard also rejects tool calls that bypass visibility.

Use Cases

This plugin is suitable for scenarios requiring automated processing of background tasks, such as:

  • Scheduling daily or weekly report generation.
  • Batch data processing that requires persistence and retries.
  • Automated workflows that should not interrupt the current user interaction.

Conclusion

autoqueue provides DSH with a complete unattended task queue solution. Through the separation of schedulers and tasks, combined with strict session isolation, it enables tasks to run silently in the background. With the file inbox, HTTP API, and React dashboard, developers can manage task flows flexibly.

For more details, see the plugin directory or the source repository.