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

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.

Optional Jev routing

Set TYPESAFE_API_KEY and DSH_ALPHA_JEV_ROUTING=1 in the master process to let Jev choose the workspace, Agent, and model for new requests without an Agent selected in the UI. A selected Agent still dispatches directly. The task engine continues to enforce the UI scope, model capabilities, filesystem boundaries, and approvals. Uncertain decisions, timeouts, and service failures fall back to the existing master LLM.

Keep the key in the master environment, outside the repository. DSH_ALPHA_JEV_ENDPOINT can point to an HTTPS service implementing the full TypeSafe v1/systemone Choice response, including choice, confidence, and probabilities. The confidence thresholds are provisional; assess routing accuracy, fallback rate, and latency on representative requests before rollout.

For source testing, load the local configuration with node --env-file=.env. Placing .env in the directory alone does not change the environment of a running master process.

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 scans every supported runtime and advertises those with an available executable. DSH_ALPHA_WORKER_PROVIDERS is an optional override to restrict candidates.

Automatic discovery checks executable availability; each runtime still needs separate authentication and a real-task check. mock exists for tests and local diagnostics only.

The dsh provider runs dsh --profile headless in the Worker's target directory and uses that machine's headless profile default model. This entry point returns final text only; per-turn model overrides and forwarding DSH's internal approvals to the master are not yet supported.

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.