Repository navigation
FAQ & Troubleshooting
Real questions, real answers. Anything not here: open an issue.
pnpm dsh web → command not found
Use pnpm exec dsh web or node apps/cli/lib/index.js web. The launcher needs a build
first: pnpm install && pnpm build.
Port already in use / want a different port
pnpm dsh web --port 3000. The UI opens at http://127.0.0.1:<port>.
First run feels empty
A fresh Web UI has no workspace until you add one — click Choose workspace, add the
directory you started dsh from, and select it. The composer stays locked until then.
Model changes don't take effect? They do — on the next request. No restart needed. If a card is disabled, check its toggle and the credential dot.
Custom endpoint answers 401 on "Fetch available models" Auto-discovery only speaks OpenAI Chat Completions / Responses listing. An Anthropic-style gateway answers 401 to an OpenAI probe — enter models by hand. That's by design, not a bug.
Image attachment refused on my custom model
Hand-entered models are text-only until declared. Add input: [text, image] to the
model in $DSH_HOME/settings.yaml (see Models & Providers).
Azure / Bedrock / Vertex / Codex not working with just an API key They authenticate natively (api-version, AWS creds + region, ADC project, OAuth). Fill what the provider card names.
Can I resume after a crash? Yes — sessions are durable event logs (JSONL/SQLite). Mailboxes, goals, schedules, and todos fold back on restart.
Context window exceeded mid-engagement
Token metering + compaction handle pressure automatically; hard overflow surfaces as a
coded failure naming the window. Trim the declared contextWindow on a hand-entered
model or move to a larger one.
Where are my keys?
$DSH_HOME/.credentials.yaml, owner-only. Settings hold only references. Removing a
key makes it unresolvable — that's intended.
[sandbox: file access denied under <mode> mode]
The sandbox did its job. Escalate through the approval path or switch the session's
sandbox mode — don't retry the same op forever.
[exit code: N] in bash output
Non-zero exit from your command, reported honestly. The harness doesn't swallow exit
codes.
Command died mid-scan
Deadlines and kill-escalation (SIGTERM → SIGKILL after graceMs) bound every exec.
Long work → run_in_background: true and read via job_output.
Windows: bash not found
The bash executor probes Git-for-Windows, the Microsoft Store build, WSL, then PATH —
or set an explicit bashPath in the shell settings. PowerShell is the first-class
Windows path (pwsh tools).
Teammate message lost after restart?
Delivery is durable and recovery retries pending messages on agent start. If a target
is offline, quiet delivery waits; wakeup targets a live agent.
Task board shows a conflict? Updates are compare-and-set — two writers can't silently overwrite each other. Re-read and retry with the fresh value.
pip install deepseek-harness-sdk then what?
from deepseek_harness import DeepSeekHarness — the bundled runtime wheel launches
with it. See Python SDK & CLI.
finish_reason: None?
No turn ended inside the run interval (e.g. the agent was still working). Steer or wait.
-
git pull— pull the latest main -
pnpm install— refresh workspace links -
pnpm build— rebuildlib/artifacts (gitignored; stale copies cause weird imports) -
pnpm dsh web— fresh boot
Still stuck → open an issue with your OS, Node version, and the failing command's output.