The dsh Web UI in one container: the CLI plus its native terminal backend baked
in, a persistent-shell agent preset, and every knob in config/ or .env.
Nothing is installed on the host but Docker.
Pin: dsh 0.2.1-rc.5 (DSH_VERSION in .env).
cp .env.example .env # fill in the provider keys
docker compose up -d --build
./scripts/url.sh # prints the launch URLOpen the printed URL: it carries a per-process launch token, the browser exchanges it for a signed cookie, and later visits to http://127.0.0.1:3080 work directly.
Everything below runs from the repo root.
| Task | Command |
|---|---|
| start | docker compose up -d |
| stop | docker compose down |
restart (re-applies config/) |
docker compose restart |
| rebuild image (Dockerfile / scripts) | docker compose up -d --build |
| status / health | docker compose ps |
| live logs | docker compose logs -f dsh |
| launch URL (changes per start) | ./scripts/url.sh |
| shell inside the container | docker compose exec dsh bash |
| dsh CLI inside the container | docker compose exec dsh dsh --version |
| resources | docker stats --no-stream deepseek-harness |
flowchart TD
q["What did you change?"] --> cfg["config/*.yml or AGENTS.md"]
q --> env[".env"]
q --> img["Dockerfile or scripts/"]
q --> skill["skill files, or the omp side"]
cfg --> r1["docker compose restart"]
env --> r2["docker compose up -d"]
img --> r3["docker compose up -d --build"]
skill --> r4["docker compose restart"]
config/ is a read-only bind mount, so edits need only a restart — the
entrypoint reinstalls the patch, AGENTS.md, and the stale-profile check on
every boot. .env is read when the container is created, hence up -d.
The token is per process, so a restarted container invalidates the old link:
./scripts/url.sh # prints the fresh URL
docker compose logs dsh | grep 'dsh web:' # same line, without the helperVisit http://127.0.0.1:3080/ directly once the cookie is set; only a restart
invalidates it.
Edit agent-default-model in config/cordis.patch.yml, then restart:
- id: agent-default-model
config:
provider: commandcode # commandcode | merge-gateway | nvidia | orcarouter | opencode | opencode-go | deepseek-official
model: deepseek/deepseek-v4-flashRoutes live in the same file under llm-pi-ai.providers. Each entry has
apiKeyEnv, api, baseURL, defaultMaxTokens, and a models list; the key
itself belongs in .env (COMMANDCODE_API_KEY, MERGE_GATEWAY_API_KEY,
NVIDIA_API_KEY, ORCAROUTER_API_KEY, OPENCODE_API_KEY,
OPENCODE_GO_API_KEY, DEEPSEEK_API_KEY). Add a provider by copying a block
and pointing apiKeyEnv at a new variable.
OpenCode ships two routes and both are pre-wired, waiting for a key:
opencode— OpenCode Console, pay-as-you-go, 78 models, all reachable through the OpenAI-compatible translator athttps://opencode.ai/inference/openai/v1.opencode-go— the Go subscription, 18 models, athttps://opencode.ai/inference/go/v1.
Two caveats come from OpenCode's own docs: -free models are restricted to the
OpenCode client and will fail from any other harness, and Go expects a real
client user agent plus an x-opencode-session header on every conversation.
Refresh the model list with
curl -H 'user-agent: deepseek-harness/1.0' https://opencode.ai/inference/v1/models.
Sessions pick the default at creation, so existing sessions keep the model they started with — start a new one after switching.
config/web.patch.yml declares the power preset (the shipped standard
preset plus the persistent shell) and selects it as the default. Edit the
plugins list or the persona.prefix block there, then restart. Another
preset becomes the default by changing agent-preset-registry.default.
Preset edits saved from the Web UI land in the profile patch, which the home
patch and this overlay both outrank — durable edits belong in
config/web.patch.yml.
config/AGENTS.md is installed to /root/.agents/AGENTS.md on every boot and
read by dsh-agent-instructions. Edit it here; it applies to new sessions after
docker compose restart. Project-level instructions go in an AGENTS.md at the
root of the mounted workspace, which the agent reads per session.
Skills are read from /root/.agents/skills inside the container. It is mounted
read-only from OMP_SKILLS_DIR (default ./agents/skills in this repo), so:
- to curate the set, point
OMP_SKILLS_DIRat a directory of skills anddocker compose up -d; - adding a skill means adding a directory with a
SKILL.md, then restart; - the mount is read-only by design — dsh never writes back into a shared skill library.
docker compose exec dsh dsh plugin --profile web add <package>Installs land in dsh-home/profiles/web/ and survive rebuilds. A full reseed
removes them; to keep one across reseeds, declare it in config/web.patch.yml.
-
npm view @deepseek-ai/dsh dist-tags— takelatest. -
Set
DSH_VERSIONin.env. -
Re-check the preset copy against the new shipped one:
docker run --rm local/deepseek-harness:<new> \ cat /usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-web-app/presets/standard.patch.yml
-
docker compose up -d --build.
On the first boot of a new version the entrypoint moves the old profile to
dsh-home/profiles.bak-<old-version>-<stamp>/ and lets dsh recreate it — an old
profile composed under a new dsh fails startup (stale plugins, duplicate
providers). Delete the backup once you no longer need the plugins installed
there. Other profiles get the same treatment; sessions are untouched.
# back up runtime state (credentials, sessions, storages, profile)
tar -czf dsh-home-$(date +%F).tgz dsh-home
# restore
docker compose down
rm -rf dsh-home && tar -xzf dsh-home-<date>.tgz
docker compose up -d.env holds the provider keys and is gitignored — back it up separately if you
do not keep the keys elsewhere.
# re-apply config/ only (keeps credentials, sessions, plugins)
docker compose restart
# wipe runtime state (credentials, sessions, plugins); config/ reseeds it
docker compose down && rm -rf dsh-home && docker compose up -d
# start the image from scratch as well
docker compose down --rmi local && docker compose up -d --build| File | Installed to | Written by dsh? | Applies |
|---|---|---|---|
config/cordis.patch.yml |
$DSH_HOME/cordis.patch.yml |
no | every boot, every profile |
config/AGENTS.md |
/root/.agents/AGENTS.md |
no | every boot |
config/web.patch.yml |
passed as --patch |
no | every boot, web profile |
agents/skills/ (or OMP_SKILLS_DIR) |
/root/.agents/skills (ro) |
no | every boot |
dsh-home/** |
— | yes | runtime data, never seeded |
dsh 0.2.x has no settings.yaml: every value is a plugin row, so all config
lives in those two patches. The Web UI writes per-entry overrides and a home
patch outranks them — it refuses a form write a patch would override, so a
pinned value is changed in the patch, not in the UI.
cordis.patch.yml— machine-level knobs that outrank every profile layer: model providers and the default route (llm-pi-ai,agent-default-model), agent-loop parallelism, bash timeout, glob/grep timeout.AGENTS.md— the ported omp rule files (engineering standards, execution discipline, git/comment/documentation discipline, operational safety).web.patch.yml— thepowerpreset declaration and the default-preset selection. A preset is an inline plugin list (no inheritance), so this file contains a copy of the shippedstandardpreset.
| Variable | Default | Effect |
|---|---|---|
DSH_VERSION |
0.2.1-rc.5 |
npm version + image tag |
DSH_PORT |
3080 |
host port; also the port dsh binds inside |
DSH_BIND_ADDR |
127.0.0.1 |
host bind address (loopback-only by default) |
PROXY_PORT |
3081 |
container-internal bridge port |
DSH_PERMISSION_MODE |
danger-full-access |
bash sandbox mode; the container is the boundary |
DSH_MAX_PARALLEL_TOOL_CALLS |
16 |
parallel tool calls per agent step |
DSH_BASH_TIMEOUT_MS |
600000 |
foreground bash timeout, and the override cap |
WORKSPACE_DIR |
./workspace |
host directory mounted at /workspace |
OMP_SKILLS_DIR |
./agents/skills |
host skill library mounted at /root/.agents/skills |
COMMANDCODE_API_KEY |
— | Command Code gateway key |
MERGE_GATEWAY_API_KEY |
— | Merge Gateway key |
NVIDIA_API_KEY |
— | NVIDIA Build key |
ORCAROUTER_API_KEY |
— | OrcaRouter key |
OPENCODE_API_KEY |
— | OpenCode Console key (pay-as-you-go) |
OPENCODE_GO_API_KEY |
— | OpenCode Go subscription key |
DEEPSEEK_API_KEY |
— | built-in DeepSeek route + web search/fetch |
TZ |
Asia/Kolkata |
timezone the agent sees |
- dsh 0.2.1-rc.5 from npm, with
node-ptyprebuilt and smoke-tested at build time (a broken native addon fails the build, not the first bash call). poweragent preset — the shippedstandardpreset plus a persistent shell: cwd, exported variables, functions, and background jobs survive across tool calls. Default for new sessions; other presets stay selectable.- Config as files:
config/is the source of truth and is mounted into the container read-only. - Runtime data on a host bind mount (
dsh-home/): credentials, sessions, storages, and the profile survive container deletion. Never committed. - Tooling for the agent:
ripgrep,jq,git,python3,pnpm. - omp parity (see below): the same gateways, model ids and env var names, the same instruction rules and skill library, and the same isolation stance.
| Aspect | Mirrored | Where |
|---|---|---|
| Gateways | commandcode, merge-gateway, nvidia, orcarouter — same base URLs, model ids and key env names as ~/.omp/agent/providers/*.yml — plus opencode and opencode-go under their own keys |
config/cordis.patch.yml (llm-pi-ai) |
| Default model | deepseek-v4-flash on Command Code — the gateway both harnesses share, so one credential refresh fixes both |
config/cordis.patch.yml (agent-default-model) |
| Instructions | 8 harness-neutral rule files from ~/.omp/agent/rules/ |
config/AGENTS.md |
| Skills | the omp skill library, read-only | OMP_SKILLS_DIR |
| Isolation | no sandbox runner inside the container (the container is the boundary), explicit destructive-command limits | DSH_PERMISSION_MODE, config/AGENTS.md |
| Parallelism | 16 parallel-safe tool calls per step | DSH_MAX_PARALLEL_TOOL_CALLS |
Deliberately not mirrored:
- omp's existing OpenCode credential. The
opencodeandopencode-goroutes are wired and ready, but they carry their own keys (OPENCODE_API_KEY,OPENCODE_GO_API_KEY) rather than borrowing the one in opencode's own auth store. - omp-only tools —
evalkernels,xd://devices,proc://services,out://— have no dsh equivalent;config/AGENTS.mdstates the mapping (persistentbash,nohup+ log files). - MCP servers. omp mounts many; add the ones you need as
dsh-mcp-clientrows rather than inheriting a set dsh's tools cannot match.
| Symptom | Cause | Fix |
|---|---|---|
| Browser shows 401 after a restart | token is per process | ./scripts/url.sh, open the fresh URL |
Reply fails with AUTH: ... |
provider rejected the key | fix the key in .env, docker compose up -d |
Reply fails with QUOTA: ... |
account out of credits | top up, or switch agent-default-model |
Reply fails with MODEL: ... |
model id not in the route's models list |
add it under llm-pi-ai.providers |
OpenCode -free model fails |
free tier only serves the OpenCode client | use a paid model or a Go key |
| Container exits during boot | patch/preset error | docker compose logs dsh — the plugin error is printed |
| Unhealthy, logs look fine | bridge died, dsh alive (or the reverse) | docker compose restart; the entrypoint exits when either process dies |
port is already allocated |
something else on DSH_PORT |
change DSH_PORT in .env, docker compose up -d |
SANDBOX_UNAVAILABLE |
in-container sandbox runner unavailable | keep DSH_PERMISSION_MODE=danger-full-access |
glob/grep time out |
ripgrep walking a huge bind-mounted tree | scope path/pattern; raise tool-fs-search.timeoutMs |
dsh: warning: ... did not activate |
stale profile from another dsh version | rm -rf dsh-home/profiles*, restart |
| Docker VM eating RAM | colima VM allocation, not containers | colima stop && colima start --memory 8 |
The container itself is small (a few hundred MB). The memory you see on macOS is
the colima VM that hosts the Docker daemon — resize it with
colima stop && colima start --memory 8, and keep kubernetes.enabled: false
in ~/.colima/default/colima.yaml unless you need the cluster. Reclaim disk
with docker builder prune after repeated rebuilds. To hand the machine back
without losing anything: docker compose down (state stays in dsh-home/).
flowchart TD
repo["deepseek-harness/"]
repo --> dockerfile["Dockerfile — node 24 + dsh + rg/jq/git/python3/pnpm"]
repo --> compose["docker-compose.yml — loopback port, bind mounts, healthcheck"]
repo --> env[".env.example — keys, ports, tuning knobs"]
repo --> config["config/ — mounted read-only at /opt/dsh-seed"]
repo --> scripts["scripts/"]
repo --> agents["agents/skills/ — default skill mount point"]
repo --> home["dsh-home/ — runtime data (gitignored)"]
repo --> workspace["workspace/ — default working directory"]
config --> homepatch["cordis.patch.yml — providers, tuning"]
config --> webpatch["web.patch.yml — power preset + default"]
config --> agentsmd["AGENTS.md — standing instructions"]
scripts --> entry["entrypoint.sh — install config, boot dsh, bridge port"]
scripts --> url["url.sh — print the launch URL"]
scripts --> pty["node-pty-smoke.cjs — build-time native check"]
sequenceDiagram
participant C as docker compose up
participant E as entrypoint.sh
participant D as dsh (127.0.0.1:3080)
participant S as socat (0.0.0.0:3081)
participant B as Browser
C->>E: container start
E->>E: install cordis.patch.yml + AGENTS.md, retire stale profile
E->>D: dsh --profile web --patch web.patch.yml --no-open
D-->>E: listening
E->>S: bridge 3081 -> 3080
B->>S: GET /?token=...
S->>D: forwarded
D-->>B: signed cookie, then the UI
- Why socat: dsh's web listener refuses wildcard binds and only accepts a concrete local address, so the process stays on loopback inside the container and a second, container-internal port is published. The URL dsh prints already names the host address.
- Why
danger-full-access: the in-process sandbox runners (bwrap/Landlock) are unreliable inside a container and fail closed withSANDBOX_UNAVAILABLE. The container is the isolation boundary instead. SetDSH_PERMISSION_MODE=workspace-writeif your host kernel allows it. - Auth is a launch token, not a password: anyone who can reach the port can
ask for a new session. Keep
DSH_BIND_ADDRon loopback, or front it with TLS and a proxy. - Boot failures are loud: a bad patch row, a preset naming an unknown plugin, or a missing profile dependency exits the container with the reason in the logs rather than serving a half-configured UI.