How-Tos
How to deploy dsh-superagent on DeepSeek Harness
Official steps to install the dsh-superagent prototype on a dedicated DeepSeek Harness profile, including the exit codes and isolation limits.
Searcher → Analyst → Writer → Editor · subagentic-20261101-2000
The deployment guide installs dsh-superagent on a dedicated DeepSeek Harness profile named superagent, created from the Web profile template. It loads the bundle and serves its panel on 127.0.0.1. Keep that profile separate from the one you work in. The plugin changes process-wide PATH and git settings, and the process needs its own restarts and upgrades.
The agent comments, pushes branches, and opens pull requests as its own GitHub user, through a GitHub CLI signed in only as that account. A Feishu bot is optional. Use the panel for Sources, Policy, and Execution.
Isolation limits
dsh-superagent-worker is for Executors and dsh-superagent-router is for the main Session. They appear in the DeepSeek Harness preset list but are intended only for dsh-superagent. Do not select them for personal Sessions or disable their configuration rows. The application needs them to create and resume its Sessions.
Both presets run with danger-full-access as the operator's OS user and read messages from subscribed Threads. Account wrappers choose the agent's credentials by default. They do not isolate the process. A worker can execute programs by path and read the operator's home directory. For isolation, use a dedicated OS account containing only the agent's credentials.
Prerequisites
- Node.js 22.19+ or 24+, pnpm, git 2.32+, Python 3.8+, and tmux
- GitHub CLI (
gh) 2.48 or later. Source CLI fields must point toghorlark-cliwrappers. - A repository on github.com. GitHub Enterprise Server is not supported. Keep a local clone if you want a worktree per Ticket, and install
git-lfsif that repository uses Git LFS. - A model provider configured for DeepSeek Harness. The profile's default model is used unless Eval or Execution names another.
- For Feishu:
lark-cli, tested with 1.0.90, and a Feishu or Lark app with a bot.
Agent account
Create a GitHub user for the agent and give it write access to the repository. A GitHub App cannot be the agent, because dsh-superagent reads the account's notifications. Give it a CLI that uses only its own credentials:
mkdir -p ~/.local/bin
cat > ~/.local/bin/gh-agent <<'EOF'
#!/bin/sh
GH_CONFIG_DIR="$HOME/.config/gh-agent" exec gh "$@"
EOF
chmod +x ~/.local/bin/gh-agent
gh-agent auth login
gh-agent api user --jq .login
Sign in as the agent account. The last command prints its login. dsh-superagent reads the login the same way. For Feishu, use the guide's bot-only wrapper and a separate configuration directory. Do not run lark-cli config remove, which would affect the shared app-secret keychain entry.
Install once
Run the deployment guide's install block once, on a machine that has no superagent profile yet. It installs the pinned public package named in that block, clones this repository, installs and builds, creates the superagent profile from the Web template, and adds this bundle as a plugin. That pinned version is public. Other versions must satisfy engines.dsh in package.json.
The profile-creation command creates ~/.dsh/profiles/superagent from the DeepSeek Harness Web template. Set DSH_HOME to relocate the default ~/.dsh directory. Run it only for a new installation. If the profile already exists, that command replaces it and deletes cordis.patch.yml, including machine configuration. Do not use it for upgrades.
Copy the example profile patch linked from the guide to ~/.dsh/profiles/superagent/cordis.patch.yml, replacing that file, and replace every placeholder. For Feishu, enable the dsh-superagent-feishu entry. The webserver entry sets the panel's port.
stateDir is required: an absolute path for the database, the lock, the shims in worker-bin, the agent's git configuration, and by default the Ticket directories in work. Back it up before upgrades. After the first start, edit machine limits in Settings → Deployment or the DeepSeek Harness Plugin Manager. Changes apply without restart. stateDir cannot be changed there. Invalid values or unknown keys prevent startup; the log identifies the key.
Start and exit codes
scripts/dsh-superagent start
scripts/dsh-superagent status
start runs dsh --profile superagent in tmux session dsh-superagent. It waits up to one minute and refuses duplicate instances. stop and restart request a graceful shutdown and wait up to five minutes for Executors. They never force-kill the process or touch other tmux sessions. Use --profile and --url, or DSH_SUPERAGENT_PROFILE and DSH_SUPERAGENT_URL, for another profile or port.
status, start, and restart exit with one of four codes:
| Code | Meaning |
|---|---|
| 0 | The service runs normally |
| 1 | It does not run, runs twice, does not answer, or its runtime reports an error; a restart may fix it |
| 2 | It runs, but a part other than the runtime reports an error; a restart does not fix it |
| 3 | It runs and waits for setup; a restart does not fix it |
A first start can exit 3 while it waits for setup. status returns failures under errors and requirements under setup. Only an intentional stop pauses automatic recovery. Open the URL printed in the log, then choose Superagent in the sidebar.
Finish setup
Setup must succeed before polling or work starts. Overview lists missing requirements. A settings change runs setup again. If you fix CLI authentication outside the application, choose Check again.
Set the GitHub repository as owner/name and the agent CLI. A new Issue or comment mentioning the account arrives on the next poll. Adding a mention by editing an Issue body does not. Post a new comment. On Policy, add the accounts that may ask for work; until a list has someone, no request becomes a Ticket. On Execution, set the directory root and a prepare command. The deployment guide's sample prepare command fetches into an existing local clone and adds a worktree for the Ticket. List personal CLIs as blocked commands. On Prompts, set the disclosure line, review bots, commit author, and auto-merge condition.
Setup verifies push access and removes environment variables whose names contain KEY, PASSWORD, SECRET, or TOKEN. Command shims in worker-bin are first on PATH; gh runs the agent's CLI. Git configuration in worker-gitconfig replaces the operator's global and system git configuration, selects the agent CLI as the github.com credential helper, rewrites GitHub SSH addresses to HTTPS, and removes GH_TOKEN and GITHUB_TOKEN. A file in those directories that dsh-superagent did not write stops setup. Credential wrappers still do not isolate the process.
From an allowed GitHub account, mention the agent login and the request. Within one minute by default, Overview should show a Ticket.
Create the hourly check in the DeepSeek Harness profile you normally use, not in superagent. The guide's prompt runs scripts/dsh-superagent --profile superagent status: say nothing on exit 0, report exit 2 and exit 3 without restarting, leave the service stopped when manually_stopped is true, and otherwise recover exit 1 with scripts/dsh-superagent --profile superagent --respect-stop restart.
Upgrade
Wait until no Executor is in the middle of a turn. Back up orchestrator.sqlite under the state directory. Run git pull && pnpm install && pnpm build, then scripts/dsh-superagent restart. Do not rerun the profile-creation command.
A database migrated by a newer version cannot be opened by an older one, so rollback needs that backup. Keep the dsh-superagent-worker and dsh-superagent-router rows in cordis.patch.yml while their Sessions are in use, or resume fails with agent-preset/not-found.
Next step
Read the install block in the deployment guide and run it only if the superagent profile does not exist. Sign the agent wrapper in, start the service script, and treat exit 3 as waiting for setup. Run the service as a dedicated OS account that contains only the agent's credentials; account wrappers do not isolate the process.