dsh-alpha

English | 简体中文 · Live site · Architecture

A control plane for dispatching coding work across machines and agent runtimes from one DSH conversation.

The demo uses an isolated environment. Machine, workspace, and path information is redacted.

The square launch film on the project site was rendered locally with the open-source HyperFrames framework.

Why dsh-alpha

Coding agents are useful on their own, but real work quickly spreads across laptops, build hosts, GPU machines, and repositories that live at different paths. dsh-alpha adds the missing control plane:

• see which machines and agents are online;
• treat the same Git repository on different machines as one logical workspace;
• route a task to the right machine, runtime, model, and permission mode;
• stream progress, approvals, cancellation, and results back into the same conversation;
• reconnect and recover durable task history when a Worker temporarily disappears.

dsh-alpha is a plugin for DSH (DeepSeek Harness). It coordinates existing provider CLIs; it does not replace their installation, authentication, or security controls.

Mental model

DSH Web / headless master
  ├─ global workspace inventory
  ├─ agent capability and load catalog
  ├─ task / approval / recovery state
  └─ reverse WebSocket gateway
          ├─ Worker A → Codex / Claude Code
          ├─ Worker B → Kimi Code / ZCode
          └─ Worker C → OpenCode / Qoder / WorkBuddy

Workers connect outward to the master, so they do not need public IP addresses. Repository identity is separated from machine-local paths, and execution remains constrained to each Worker's explicit allowed roots.

Highlights

Capability	What it changes
Global workspace inventory	One repository can be recognized across several machines and local paths.
Repository-aware scheduling	Prefer a Worker that already has the repository; clone on demand only inside an allowed root.
Per-turn Worker controls	Select Agent, model, reasoning effort, and permission mode without leaving the conversation.
Event-driven results	Dispatch once, wait on events, and resume with the same durable task ID after interruption.
Approval handoff	Worker approval requests return to the active Alpha session instead of hanging invisibly.
Reverse gateway	Workers connect to the master through authenticated WebSocket sessions and reconnect automatically.
Operational tooling	Web sidebar, headless runner, status CLI, Worker doctor, and multi-device acceptance checklist.

Quick start

Requirements

• Node.js 22.13 or newer (task events use the built-in SQLite module)
• DSH 0.1.0-rc.8 or newer
• pnpm (used by dsh plugin)
• the provider CLI you want to run, already installed and authenticated on the machine that executes it

dsh --version
pnpm --version

DSH Web

dsh plugin --profile web add dsh-alpha
node ~/.dsh/profiles/web/node_modules/dsh-alpha/scripts/install-preset.mjs
dsh web

Open Alpha master from the Web sidebar, choose a workspace or keep automatic routing enabled, then start a conversation.

Headless master

dsh plugin --profile alpha add dsh-alpha
node ~/.dsh/profiles/alpha/node_modules/dsh-alpha/scripts/install-alpha-profile.mjs
dsh --profile alpha "Use list_agents, dispatch a short task, and report the result."

The installer updates only the dsh-alpha managed block and preserves configuration outside it.

Develop from source

git clone https://github.com/songofhawk/dsh-alpha.git
cd dsh-alpha
npm install
npm run setup
npm test

Add a remote Worker

Configure one token per Worker on the master:

export DSH_ALPHA_GATEWAY_HOST=0.0.0.0
export DSH_ALPHA_GATEWAY_PORT=4310
export DSH_ALPHA_GATEWAY_TOKENS='build-1:replace-with-a-long-random-token'

Install and start the Worker on the target machine:

npm install dsh-alpha

export DSH_ALPHA_HUB_URL='ws://<master>:4310/'
export DSH_ALPHA_WORKER_MACHINE_ID='build-1'
export DSH_ALPHA_WORKER_TOKEN='replace-with-a-long-random-token'
export DSH_ALPHA_WORKER_ALLOWED_ROOTS='/work'

./node_modules/.bin/dsh-alpha-worker-doctor
./node_modules/.bin/dsh-alpha-worker

Use wss:// and network-level source restrictions outside a trusted LAN or VPN. Keep tokens out of repositories, URLs, screenshots, and process logs.

Supported runtimes

The default set is Codex, Claude Code, and Kimi Code. Optional runtimes must be enabled explicitly.

Provider ID	Runtime	Default
codex	Codex app server / CLI	Enabled
claude-code	Claude Code headless	Enabled
kimi-code	Kimi ACP	Enabled
zcode	Zhipu ZCode headless	Opt-in
opencode	OpenCode ACP	Opt-in
qoder	Qoder headless	Opt-in
workbuddy	Tencent WorkBuddy via codebuddy	Opt-in

Each runtime is installed and authenticated independently. mock exists for tests and local diagnostics only.

Daily workflow

1. list_workspaces resolves the logical repository and its machine locations.
2. list_agents exposes availability, capabilities, load, and workspace affinity.
3. dispatch_task returns a durable taskId; wait_task follows the event stream without busy polling.
4. agent_approve or agent_cancel resolves Worker approvals in the current Alpha session.
5. task_status and task_result recover disconnected or historical work.

The Web workspace selector can create a hard machine/workspace constraint. With no manual selection, the scheduler may choose a matching Worker and clone the Git workspace into its allowed root.

Safety defaults

• Gateway startup fails closed when authentication tokens are missing.
• Every local and remote path is checked against explicit allowed roots.
• Clone destinations are chosen by the Worker, never by an arbitrary task path.
• Web master and headless master must not share one gateway port.
• Health endpoints expose liveness and Worker counts, not identities or secrets.
• Worker doctor is read-only and never prints the Worker token.
• Approval, cancellation, reconnect, and interrupted-task behavior are covered by automated tests.

Useful commands

dsh-alpha status
dsh-alpha web
dsh-alpha run "summarize the current workspace"
dsh-alpha-worker-doctor
dsh-alpha-worker
npm test

Documentation

• Design and architecture
• Deployment guide
• Multi-device acceptance checklist
• LAN access bundle
• Vendored adapter notes
• Launch article: Chinese / English
• Doco publication: Chinese / English

Project status

Current public source version: 0.2.1. The repository covers local orchestration, reverse-gateway Workers, repository-aware scheduling, recursive masters, approval forwarding, global workspace selection, durable task recovery, and seven production runtime integrations.

Before upgrading a running installation, rerun the matching preset/profile installer and execute the acceptance checklist for every connected machine.