dsh Container Image
DeepSeek Harness (dsh) as a batteries-included
container: agent, full toolchain, and reverse proxy in one image, built from the official source tags.
English | 中文
Quick start
Docker Compose (Linux)
docker compose -f examples/compose.yaml up -d
docker compose logs dsh | grep 'dsh web:'
# open http://127.0.0.1:3081/ in your local browser (the proxy redirects to dsh's launch token)
Podman Quadlet (Linux, recommended)
sudo mkdir -p /etc/containers/systemd
sudo cp examples/dsh.container /etc/containers/systemd/
sudo systemctl daemon-reload
sudo systemctl enable --now dsh.service
Both examples publish 127.0.0.1:3081 and mount one volume at /home/dsh. The user layer
(~/.dsh, caches, user-installed tools) survives image upgrades; the system layer comes from
the image. The first visit is redirected to dsh's launch token, and the browser keeps the session
cookie from then on, so there is no separate login form.
What's inside
| Component | Description |
|---|---|
| Base image | debian:13-slim (moving tag; pass BASE_IMAGE to pin a digest) |
| Toolchain | Node.js 24 LTS, pnpm, uv, Rust/cargo (+ rustfmt/clippy), git + git-lfs, build-essential + musl-tools, Caddy, podman + crun, gh, yq. These are image-owned real binaries and upgrade with the image |
| Agent CLI tools | ripgrep, fd, python3, zip, openssh-client, tmux, sqlite3, vim.tiny/nano, less, rsync, wget, tree, htop, tzdata, patch, plus a diagnostics set (dig/nc/socat/traceroute/iperf3/nft, file, ncdu, strace, zstd/lz4, bc, moreutils, pv, uuid-runtime), xdg-user-dirs (UI default workspace) and dev tooling (just, shellcheck). All of them are baked into the system layer, so a fresh container never re-downloads them (a runtime apt install would be lost on recreation) |
| Nested containers | podman in-container (rootless) with XDG_RUNTIME_DIR, subuid/subgid and the network/sysctl defaults preconfigured; the host runtime must allow unprivileged user namespaces + /dev/fuse + /dev/net/tun and must not mask the container's /proc (--security-opt unmask=ALL, Quadlet Unmask=ALL, Docker systempaths=unconfined); resource limits (--memory/--cpus) inside nested containers are not enforced (cgroup v2 constraint); see docs/deployment.md § In-container podman |
| dsh | Built from the official source tag into /opt/deepseek-harness (DSH_TAG pinnable; latest builds the newest upstream tag, the only one the smoke gate verifies); no runtime auto-update |
| Exposure | Caddy reverse proxy (0.0.0.0:3081 → dsh's 127.0.0.1:3080); preserves the browser Host/Origin, redirects the first visit to dsh's login token, and keeps optional basic auth |
| Supervisor | dsh web auto-restarts on exit; docker exec dsh dsh-restart restarts it manually |
| Remote compatibility | One container-adapt plugin (container/plugin/, mounted via dsh --patch): writes dsh's launch token for the proxy login redirect (the browser holds the session cookie), hides the headless-hostile "Open config file" button (describe reports no local document), serves the build-time-extracted images from /container-assets/*, and registers a built-in card on the Plugins page |
| Observability | OCI labels, HEALTHCHECK (validates expected unauthenticated statuses on 3080 + 3081) |
| Runtime user | uid 1000 (dsh), passwordless sudo; /home/dsh is the persisted user layer |
Container-adapt plugin
All container-side adaptation of upstream dsh (0.2.1-alpha.3 and newer) lives in one Cordis plugin,
shipped with the image at /opt/dsh-container-plugin and mounted into the web profile via
dsh --patch:
- Launch-token redirect: the plugin writes dsh's process launch token to
/tmp/dsh-caddy/launch-token; Caddy 302s a browser without a session cookie to/?token=..., and dsh sets anHttpOnly; SameSite=Strictcookie. The container never injects or rewrites the session; the browser holds it. - Hidden settings-document button: "Open config file" has no headless fallback upstream and
would spawn
xdg-openinto nothing in a container. The plugin makessettings/describereporthasDocument: false, so the button never renders (upstream's own UI logic). Settings persist on the mounted volume under~/.dsh(upstream v0.1.7+ keeps them per profile in~/.dsh/profiles/<profile>/cordis.patch.yml; the legacysettings.yamlis imported once). - Plugins page card: a small client half registers a built-in
plugins.itemcard (no enable/disable switch) with a one-line summary and a detail page describing the plugin and linking the project repository. - Payload post-processing: three build-time steps run after
pnpm run build:official. Images inlined at ≥ 100 KiB are extracted to/container-assets/<content-hash>(servedimmutableby the plugin, fetched only when the screen that uses them opens), the client bundles are minified with esbuild, and the.dsh-buildrecord is refreshed so it keeps matching the delivered artifacts.
This plugin is the single adaptation maintenance point. When upstream ships an API that makes part of it redundant, that part is deleted rather than kept around; the removal shows up in the commit that follows the upstream tag. docs/upstream-contract.md § Simplification triggers is the checklist reviewed on every upstream release.
Networking & security
- Port model:
dsh weblistens on127.0.0.1:3080(upstream rejects--host 0.0.0.0); the exposed port is3081, published on host loopback by the examples. - The proxy preserves the fence: Caddy forwards the browser
Host/Originunchanged, and dsh's/apifence is real. External authorities must be listed inDSH_TRUSTED_HOST(or derived fromDSH_PUBLIC_URL); Caddy rejects any other Host with 403, which is what stops DNS rebinding. Anyone who can reach3081can log in, so enable basic auth (DSH_PROXY_USER/DSH_PROXY_PASSWORD, set together or the supervisor refuses to start) and keep the port firewalled. The/api/remote.muxWebSocket is exempt from basic auth (browsers do not reliably attachAuthorizationto upgrades) and is authenticated by the browser'sSameSite=Strictcookie. - Session held by the browser: the first visit without a cookie is 302'd to dsh's launch token; dsh sets the session cookie and the browser sends it back. There is no server-side cookie injection. DeepSeek account sign-in still requires a loopback browser origin (an SSH tunnel) rather than a public hostname; see docs/deployment.md § DeepSeek account sign-in.
- Streams, payload and caching: SSE/WebSocket pass through unbuffered (verified against Caddy
2.6) and dsh's 2 s heartbeat survives the hop. The client bundles are post-processed at build
time, so a cold page load measured in a headless browser is ≈1.6 MiB on the wire against
≈5.8 MiB for upstream's unprocessed payload. The combined client-plugin bundle drops from 5.06 MiB
to ≈1.0 MiB gzip, because images inlined at ≥ 100 KiB are extracted and fetched only when their
screen opens, and the bundles are minified. The index is
no-storewhile the content-hashed/assets/*tree is servedimmutable, so repeat visits are cheap. - Telemetry off by default: the entrypoint sets
DSH_TELEMETRY_MODE=DISABLED, so the OTel feedback uploader never sends anything unless you opt back in. Separately, upstream's DeepSeek session-log contributor is on by default and attaches session-log suffixes to DeepSeek API requests; docs/security.md covers what it sends and how to turn it off. - Extra args: pass
dsh webarguments through the container command, e.g.["--port", "8080"](internal port only; the exposed port stays3081).
For WAN access, terminate TLS in front of 3081; the docs include a working nginx config with
WebSocket headers and raised timeouts. See docs/deployment.md and
docs/security.md.
Environment variables
| Variable | Default | Description |
|---|---|---|
DSH_PROXY_USER / DSH_PROXY_PASSWORD |
(empty) | Basic auth on the exposed proxy (recommended for any non-loopback deployment); set both or neither. /api/remote.mux is exempt and uses the dsh session cookie |
DSH_PUBLIC_URL |
http://127.0.0.1:3081/ |
Browser-facing root advertised to dsh/agent context and used by the launch-token URL. Set it to the real external URL for LAN/public; it grants no trust |
DSH_TRUSTED_HOST |
(empty; derived from DSH_PUBLIC_URL) |
Comma-separated extra authorities (host or host:port) accepted by dsh's fence and Caddy's Host allowlist |
DSH_TELEMETRY_MODE |
DISABLED |
OTel feedback-upload policy; FEEDBACK_ONLY restores the upstream default (uploads on explicit feedback), DISABLED keeps the OTel path local. It does not control the DeepSeek session-log contributor (security.md) |
Everything else uses built-in defaults: dsh data at ~/.dsh, cwd $HOME, writable caches under
~/.cargo / ~/.local/share, image-owned tools in /usr/local/bin and /opt/rust. dsh/agent
temporary files default to ~/.dsh/tmp (TMPDIR); /tmp itself stays ephemeral for the launch
token, Caddyfile and dsh-web PID. The whole /home/dsh is the persistence boundary: mount it as
one volume; image upgrades replace the toolchain, never the data. Details in
docs/build.md and docs/deployment.md.
Documentation
| Document | Contents |
|---|---|
| docs/deployment.md | Deployment & maintenance: Compose, Quadlet, remote access, offline use, FAQ |
| docs/security.md | Security notes: network exposure tradeoff, credentials, trusted workloads |
| docs/build.md | Build configuration: build args, source tag pinning, and why the toolchain floats |
| docs/releasing.md | Releasing: tag-triggered publish, light/heavy gates, upstream tag watcher, failure diagnostics |
| docs/upstream-contract.md | The upstream behaviors this image depends on, and how each one is enforced |
| docs/development.md | Directory structure and local development |
No comments yet. Be the first to write one.