dsh Container Image

Containerized DeepSeek Harness (dsh), built on a small debian:13-slim base with only the toolchains this project needs: Node.js LTS, pnpm, uv, Rust/cargo, Caddy, podman, and GitHub CLI. It is ready to use out of the box with optional dsh auto-update baked in. The image is published to GitHub Container Registry; both the compose.yaml and the Quadlet .container examples pull the image directly — no local build needed.

dsh itself comes from the official repository deepseek-ai/deepseek-harness and is installed the way the official README describes: install Node.js, then npm-install @deepseek-ai/dsh.

Features

The base image is pinned by default; the dsh top-level version and Rust toolchain can be pinned with --build-arg. uv/pnpm are installed as user-level tools, and Caddy/podman/gh come from apt — see build.md.

Environment variables

Everything else uses built-in defaults:

• dsh data: ~/.dsh (/home/dsh/.dsh) — upstream default, no DSH_HOME override
• working directory: $HOME (/home/dsh); dsh creates folders under it as needed
• Rust/cargo: ~/.rustup + ~/.cargo
• uv: ~/.local/bin (managed Python/tool data in ~/.local/share/uv)
• pnpm: ~/.local/share/pnpm

The whole /home/dsh directory is the persistence boundary: mount it as one volume so user-level state survives while /usr/local and the rest of the system layer are reset on image upgrades. User-level tools (Rust/uv/pnpm/dsh) are baked into the image and copied into a fresh named volume on first start; system packages installed later with sudo apt live in the container/system layer and are not part of the persistent home volume.

The exposed port is 3081: a Caddy reverse proxy inside the container listens on 0.0.0.0:3081 and forwards to dsh web on 127.0.0.1:3080, rewriting Host/Origin to loopback. UI assets are gzip-compressed by the proxy (≈1.3 MB → ≈360 KB), which matters most for remote access; SSE/WebSocket streams pass through unbuffered (verified against Caddy 2.6), so agent output is not delayed by the proxy. For WAN access, terminate TLS with an external reverse proxy in front of 3081; it must forward the WebSocket upgrade headers (proxy_set_header Upgrade $http_upgrade / proxy_set_header Connection "upgrade" with nginx) and must not buffer or time out quiet streams — see deployment.md for a working example. dsh's /api browser-trust fence checks HTTP headers only, so remote browsers pass every endpoint — including settings/credentials methods that are otherwise loopback-only. The proxy is therefore the security boundary: anyone who can reach 3081 gets full control, so enable DSH_PROXY_USER/DSH_PROXY_PASSWORD and keep the port firewalled. Extra dsh web arguments can be passed through the container command, e.g. ["--port", "8080"] (changes only dsh's internal port; the exposed port stays 3081).

Inside the container, dsh web is supervised by dsh-web: if it exits or crashes it is restarted automatically. To restart it manually without restarting the container, run:

docker exec dsh dsh-restart

Quick start

Docker Compose (Linux)

docker compose -f examples/compose.yaml up -d
# open http://127.0.0.1:3081

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

Persistence — both examples mount one volume at /home/dsh. This is the user layer: ~/.dsh, ~/.cargo, npm/cache/config files, dsh-created working folders, and user-installed tools survive image upgrades; the system layer (/usr/local, apt packages) comes from the new image.

Networking — dsh web listens on 127.0.0.1 (npm releases reject --host 0.0.0.0); the entrypoint runs a Caddy reverse proxy on 0.0.0.0:3081 that rewrites Host/Origin to loopback (→ dsh's 127.0.0.1:3080), so the examples can use plain bridge networking with port 3081 published. See security.md and the deployment guide for details.

Documentation

License

MIT