dsh-container

dsh Container Image

DeepSeek Harness (dsh) as a batteries-included container — agent, full toolchain, and a 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 while the system layer comes from the image. The first visit is redirected to dsh's launch token and the browser keeps the session cookie; there is no separate login form.

What's inside

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 an HttpOnly; SameSite=Strict cookie. 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-open into nothing in a container. The plugin makes settings/describe report hasDocument: 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 legacy settings.yaml is imported once).
• Plugins page card — a small client half registers a built-in plugins.item card (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> (served immutable by the plugin, fetched only when the screen that uses them opens), the client bundles are minified with esbuild, and the .dsh-build record 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 (see docs/upstream-contract.md § Simplification triggers for the checklist reviewed on every upstream release).

Networking & security

• Port model — dsh web listens on 127.0.0.1:3080 (upstream rejects --host 0.0.0.0); the exposed port is 3081, published on host loopback by the examples.
• The proxy preserves the fence — Caddy forwards the browser Host/Origin unchanged; dsh's /api fence is real. External authorities must be listed in DSH_TRUSTED_HOST (or derived from DSH_PUBLIC_URL); Caddy rejects any other Host with 403, which is what stops DNS rebinding. Anyone who can reach 3081 can log in: 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.mux WebSocket is exempt from basic auth (browsers do not reliably attach Authorization to upgrades) and is authenticated by the browser's SameSite=Strict cookie.
• 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), not a public hostname — see docs/deployment.md § DeepSeek account sign-in.
• Streams, payload & 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 instead of ≈5.8 MiB: the combined client-plugin bundle drops from 5.06 MiB to ≈1.0 MiB gzip (images inlined at ≥ 100 KiB are extracted and fetched only when their screen opens, and the bundles are minified). The index is no-store while the content-hashed /assets/* tree is served immutable, 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. Separate from it, upstream's DeepSeek session-log contributor is on by default and attaches session-log suffixes to DeepSeek API requests — see docs/security.md for what it sends and how to turn it off.
• Extra args — pass dsh web arguments through the container command, e.g. ["--port", "8080"] (internal port only; exposed port stays 3081).

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

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

License

MIT