Skip to content

About

Deep seek harness configuration

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

DeepSeek Harness (dsh) in Docker

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).

First install

cp .env.example .env            # fill in the provider keys
docker compose up -d --build
./scripts/url.sh                # prints the launch URL

Open 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.

Daily operations

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

Which command applies my change?

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"]
Loading

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.

Get back in after a restart

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 helper

Visit http://127.0.0.1:3080/ directly once the cookie is set; only a restart invalidates it.

Change the model or route

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-flash

Routes 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 at https://opencode.ai/inference/openai/v1.
  • opencode-go — the Go subscription, 18 models, at https://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.

Change the agent preset or persona

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.

Change the standing instructions

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

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_DIR at a directory of skills and docker 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.

Install a plugin

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.

Bump the dsh version

  1. npm view @deepseek-ai/dsh dist-tags — take latest.

  2. Set DSH_VERSION in .env.

  3. 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
  4. 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 and restore

# 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.

Reset

# 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

Configuration map

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 — the power preset declaration and the default-preset selection. A preset is an inline plugin list (no inheritance), so this file contains a copy of the shipped standard preset.

.env reference

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

What's inside

  • dsh 0.2.1-rc.5 from npm, with node-pty prebuilt and smoke-tested at build time (a broken native addon fails the build, not the first bash call).
  • power agent preset — the shipped standard preset 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.

Harness parity with omp

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 opencode and opencode-go routes 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 — eval kernels, xd:// devices, proc:// services, out:// — have no dsh equivalent; config/AGENTS.md states the mapping (persistent bash, nohup + log files).
  • MCP servers. omp mounts many; add the ones you need as dsh-mcp-client rows rather than inheriting a set dsh's tools cannot match.

Troubleshooting

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

Resource hygiene

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/).

Layout

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"]
Loading
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
Loading

Notes

  • 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 with SANDBOX_UNAVAILABLE. The container is the isolation boundary instead. Set DSH_PERMISSION_MODE=workspace-write if 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_ADDR on 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.

About

Deep seek harness configuration

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages