deepseek-harness/README.md

DeepSeek Harness — trusted container build

Auditable, immutable container images of DeepSeek Harness (dsh), built from the official npm release and served from this Gitea.

Upstream ships no container image. Community images ship someone else's build.
This repo turns the official release into an image whose every byte you can trace — and keeps it that way on a schedule.

---

dsh is DeepSeek's open-source agent harness: a browser UI that drives an AI agent with shell access over a workspace. It is distributed only as the npm package @deepseek-ai/dsh, so anyone who wants it in a container either trusts a third-party image or builds their own. This repository is the "build your own" option, done properly: the upstream source is mirrored here, the image installs the exact pinned official release on a slim Node base, and CI re-verifies and republishes on a cadence — without ever changing what a running deployment executes.

Status. The deployed version is pinned to 0.1.1-rc.2. Newer upstream releases are built and published automatically as their own tags (currently up to 0.1.5-rc.2) but nothing moves until the template is edited by hand — see Versions and upgrades for why, and for what changed in 0.1.2+ before you jump.

Contents

• Why this image
• Highlights
• Quick start
• Unraid
• Image contract
• Versions and upgrades
• Plugins
• Security model
• How it stays current
• Validating a third-party image
• Repository layout
• License

Why this image

Three things went wrong with the alternatives, and this repo is shaped by each:

• A community image is an unverifiable build. The obvious candidate, runzhliu/deepseek-harness, turned out to be honest — this repo's forensic workflow found its dsh code byte-identical to the official release — but that took a filesystem-level diff to establish, and a 1.6 GB image bundling a Chromium desktop was never going to be re-audited on every update. Here the provenance is a chain you can follow: upstream tag → upstream npm release → this Dockerfile → this registry, with the Dockerfile in plain sight and no upstream code modified.
• :latest silently upgraded a live deployment. A routine container restart pulled a moving tag and jumped from 0.1.1-rc.2 to the 0.1.2 line, which added mandatory launch-token auth and swapped the API gateway — breaking remote access and a plugin in one go. So this registry publishes immutable version tags only. There is no :latest, and CI is incapable of re-pushing an existing tag.
• Upstream refuses to bind 0.0.0.0 from the CLI, on purpose (the web UI can execute code). The image doesn't patch that out; it uses upstream's own supported opt-in — a --patch launcher layer — so the safety intent survives and exposure is decided entirely by which ports you publish.

Highlights

Provenance & integrity

• Official release, pinned exactly. npm install -g @deepseek-ai/dsh@<version> from registry.npmjs.org, nothing else. The version is a build argument with a known-good default.
• Immutable tags. <version> for each upstream release, <version>-r<N> for a toolchain refresh of the same release. A tag's digest never changes.
• Smoke-tested before push. Every build must report the intended dsh and pnpm versions and boot the web server with the baked patch and answer HTTP on its non-loopback interface — so a release the patch no longer applies to fails in CI, loudly, not on your NAS.
• Toolchain and recipe freshness. CI compares the newest build of the pinned version against the current pnpm release, the current node:22-bookworm-slim digest (where npm itself comes from), and a hash of the build recipe; if any moved, it publishes a -r<N> revision — so an image-level fix reaches the deployment without waiting for an upstream release.

Runtime hygiene

• Volume ownership repairs itself. A bind mount arrives with the host's ownership, which is why a fresh appdata directory used to kill dsh with EACCES … mkdir '/home/node/.dsh/profiles/web'. The entrypoint starts as root purely to take ownership of the state volume, then drops to PUID:PGID (default 1000:1000, the Unraid PUID/PGID convention) with setpriv. No manual chown step.
• Non-root where it counts, volume-confined. dsh — the process reachable from the network — never runs as root, and nothing setuid is left for it to climb back through. Everything writable (dsh state, plugin installs, pnpm's store, cache and config) lives inside the /home/node/.dsh volume; verified a full plugin install writes zero bytes to the rootfs.
• Headless by contract. --no-open is baked into CMD; a server never launches a browser (on 0.1.2+ an in-container browser could burn the one-time launch token).
• Plugin manager works in-container. pnpm is present on PATH, and dsh is wrapped so a root docker exec re-execs as the runtime user — plugin installs can't leave root-owned files that break the next start.

Operations

• Upstream mirror. The master branch tracks GitHub's master exactly, synced every six hours. (Upstream's own dsh-v* tags are deliberately not mirrored — this repo's tag list is exclusively its image releases; each release links to the upstream tag.)
• Releases. Every image tag gets a matching v<tag> release — digest, toolchain versions, the upstream release's English highlights, and the deployment caveats that apply to that version — generated by CI from the image's own provenance labels.
• Forensic validation workflow. A manual job that diffs any third-party deepseek-harness image on the host against the trusted build without executing it.

Quick start

mkdir -p dsh/state dsh/workspace

docker run -d --name dsh -p 3080:3080 \
  -v "$PWD/dsh/state:/home/node/.dsh" \
  -v "$PWD/dsh/workspace:/workspace" \
  gitea.milesward.dev/mward4/deepseek-harness:0.1.1-rc.2-r1 \
  web --patch /opt/deepseek-harness/web.cordis.patch.yml --no-open --trusted-host $(hostname)

open http://$(hostname):3080

No chown needed — the entrypoint takes ownership of the state volume at startup and then drops privileges. The one load-bearing flag is --trusted-host: it must name every hostname or IP you will open the UI at (port-less entries match any port). Without it, anything but a loopback Host header gets HTTP 403 on /api — that's upstream's DNS-rebinding/CSRF fence doing its job, not a broken container.

The image is linux/amd64 and linux/arm64.

Unraid

No first-run preparation is required: point the template at a path and start it. The container takes ownership of its own state volume on every start, so a freshly created appdata directory works immediately. If your appdata is owned by something other than 1000:1000 and you'd rather keep it that way (Unraid's share default is 99:100), set PUID/PGID to match and dsh runs as those ids instead.

Add the container from the template below (Docker tab → Add Container → paste, or drop it in /boot/config/plugins/dockerMan/templates-user/). Two fields are the whole operating contract:

• Repository is an explicit version tag. Never :latest — it doesn't exist here.
• Post Arguments replace the image command entirely. Always start with web --patch /opt/deepseek-harness/web.cordis.patch.yml --no-open, then add one --trusted-host per name you'll browse from.

<?xml version="1.0"?>
<Container version="2">
  <Name>DeepSeek-Harness</Name>
  <Repository>gitea.milesward.dev/mward4/deepseek-harness:0.1.1-rc.2-r1</Repository>
  <Registry>https://gitea.milesward.dev/mward4/deepseek-harness</Registry>
  <Network>bridge</Network>
  <Shell>sh</Shell>
  <Privileged>false</Privileged>
  <Project>https://github.com/deepseek-ai/deepseek-harness</Project>
  <Support>https://gitea.milesward.dev/mward4/deepseek-harness/issues</Support>
  <Overview>
DeepSeek Harness (dsh) - browser-based agent runtime from DeepSeek AI, packaged from the official npm release (built and served from this Gitea).

NO SETUP STEP NEEDED: the container takes ownership of its own appdata at startup, then drops to PUID:PGID (default 1000:1000) before dsh runs - so a freshly created appdata directory just works, with no chown from the Unraid terminal. If you keep appdata owned by Unraid's usual nobody:users (99:100), set PUID=99 and PGID=100 below and dsh runs as those ids instead.

SECURITY - READ BEFORE EXPOSING: the dsh Web UI has no authentication or TLS (before 0.1.2), and its web API can execute code on this container. Anything that can reach the port can run commands. Keep it on a trusted LAN, or put an authenticated reverse proxy (e.g. Cloudflare Access, Authelia) in front. Never port-forward it directly to the internet.

POST ARGUMENTS REPLACE THE IMAGE COMMAND ENTIRELY. Always include the patch flag and --no-open, then your trusted hosts:
  web --patch /opt/deepseek-harness/web.cordis.patch.yml --no-open --trusted-host YOUR-HOST [--trusted-host YOUR-HOST2]
Without a matching --trusted-host, non-loopback requests get HTTP 403 on /api - that is upstream's DNS-rebinding/CSRF fence working as intended.

The Settings/credentials pages are additionally restricted to loopback pages by upstream design; edit them via SSH tunnel (ssh -L 3080:127.0.0.1:3080 root@unraid-ip, then browse http://127.0.0.1:3080). The @goodandready/dsh-lanmode community plugin can lift that restriction on dsh 0.1.1 (it is NOT compatible with 0.1.2+, and it is third-party code that disables an upstream security fence - review it before trusting it with your credentials).

VERSIONS: this registry publishes immutable version tags only - NO :latest. dsh is a developer preview with breaking changes between releases (0.1.2 adds mandatory launch-token auth: token in docker logs, rotates every restart; 0.1.5 migrates session logs to a format that cannot be downgraded). Upgrade by editing this tag deliberately, after backing up appdata. Tags like 0.1.1-rc.2-rN are the same dsh version rebuilt with a patched toolchain or an image fix - safe to move to within the same dsh version.

PLUGINS: manage them with dsh's own tooling, e.g.
  docker exec DeepSeek-Harness dsh plugin --profile web add|update|remove PACKAGE
pnpm ships in the image and dsh re-execs as the runtime user, so this cannot leave root-owned files in appdata.

Your DeepSeek API key can be set below (stored in the container env) or entered later in Settings once running.
  </Overview>
  <Category>AI: Tools:</Category>
  <WebUI>http://[IP]:[PORT:3080]</WebUI>
  <TemplateURL/>
  <Icon>https://gitea.milesward.dev/mward4/deepseek-harness/raw/branch/main/assets/deepseek-logo.png</Icon>
  <ExtraParams/>
  <PostArgs>web --patch /opt/deepseek-harness/web.cordis.patch.yml --no-open</PostArgs>
  <Config Name="WebUI Port" Target="3080" Default="3080" Mode="tcp" Description="dsh Web UI. Reachable by everything on your LAN - see the security note in the Overview." Type="Port" Display="always" Required="true" Mask="false">3080</Config>
  <Config Name="DeepSeek API Key" Target="DEEPSEEK_API_KEY" Default="" Description="Optional. Official DeepSeek API key (sk-...). Can also be configured later in the dsh Settings UI." Type="Variable" Display="always" Required="false" Mask="true"></Config>
  <Config Name="DSH Home" Target="/home/node/.dsh" Default="/mnt/user/appdata/deepseek-harness" Mode="rw" Description="Persistent dsh state: settings, credentials, sessions, plugins. Ownership is adjusted automatically at startup - no chown needed. Back this path up." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/deepseek-harness</Config>
  <Config Name="Workspace" Target="/workspace" Default="/mnt/user/appdata/deepseek-harness/workspace" Mode="rw" Description="The agent's working directory. Only mount data you are willing to let the agent read and modify. The mount point is made writable automatically; existing files inside keep their ownership unless you set DSH_CHOWN_WORKSPACE=1." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/deepseek-harness/workspace</Config>
  <Config Name="PUID" Target="PUID" Default="1000" Description="User id dsh runs as, and the owner applied to the appdata volume at startup. Set to 99 to keep Unraid's usual nobody ownership." Type="Variable" Display="advanced" Required="false" Mask="false">1000</Config>
  <Config Name="PGID" Target="PGID" Default="1000" Description="Group id dsh runs as. Set to 100 (users) alongside PUID=99 for Unraid's usual share ownership." Type="Variable" Display="advanced" Required="false" Mask="false">1000</Config>
  <Config Name="Take ownership of Workspace" Target="DSH_CHOWN_WORKSPACE" Default="0" Description="Set to 1 to recursively chown the Workspace contents to PUID:PGID at startup, so the agent can modify files that arrived owned by someone else. Off by default - it rewrites ownership across your data." Type="Variable" Display="advanced" Required="false" Mask="false">0</Config>
</Container>

Behind a Cloudflare Tunnel, add the public hostname as a --trusted-host and have the tunnel rewrite Host to that name (and strip Origin) so the fence sees a name it trusts.

Image contract

Base	node:22-bookworm-slim + git + ca-certificates
Installed	@deepseek-ai/dsh@<version> and pnpm@<version> as npm globals (exact versions recorded as image labels)
Runs as	PUID:PGID, default 1000:1000. The entrypoint starts as root to repair volume ownership, then setprivs down — dsh itself is never root.
ENTRYPOINT	["docker-entrypoint.sh"] — fixes ownership, drops privileges, execs dsh "$@"
CMD	["web", "--patch", "/opt/deepseek-harness/web.cordis.patch.yml", "--no-open"]
Port	3080
/home/node/.dsh	DSH_HOME — settings, credentials, sessions, plugins, pnpm store/cache/config. Mount this. Taken over at startup.
/workspace	The agent's working directory (WORKDIR). Mount only what the agent may read and modify. Mount point made writable; contents untouched unless DSH_CHOWN_WORKSPACE=1.
/opt/deepseek-harness/web.cordis.patch.yml	The baked bind patch: webserver.host: 0.0.0.0, port: 3080
Env	PUID, PGID, DSH_CHOWN_WORKSPACE, plus DSH_HOME / PNPM_HOME / XDG_* pinned into the state volume
Labels	dev.milesward.dsh-version, .pnpm-version, .base-digest, .recipe-hash — what CI's freshness check reads

Three rules that are easy to get wrong:

• --patch must come immediately after web. It's a launcher flag; placed after the web command's own flags it fails with unknown option '--patch'.
• Nothing deployment-specific is baked in. No --trusted-host, no keys, no hostnames. Those are yours to supply.
• Don't pass --user. Doing so blocks the ownership repair; the entrypoint then verifies the volume is writable and, if it isn't, exits with one line naming the fix instead of a Node stack trace. Use PUID/PGID to change ids instead.

Versions and upgrades

Tag	dsh	Role
0.1.1-rc.2-r1	0.1.1-rc.2	Pinned / deployed. Adds the self-healing volume ownership fix.
0.1.1-rc.2	0.1.1-rc.2	Superseded by -r1: needs a manual chown -R 1000:1000 on appdata.
0.1.2-rc.1	0.1.2-rc.1	First launch-token release; Remote gateway replaces the ApiProxy.
0.1.5-rc.1	0.1.5-rc.1	Upstream npm latest. Session format V3 — no downgrade once migrated.
0.1.5-rc.2	0.1.5-rc.2	Upstream npm next. Feedback-dialog and file-card refinements on top of rc.1.

The full list, with digests and notes, is on the Releases page — one release per image tag, published by CI.

A -r<N> suffix means the same dsh version rebuilt with a patched toolchain or an image fix, so moving between X and X-rN is safe and needs no preparation. Changing the dsh version is the deliberate part.

dsh is a developer preview and upstream says so: expect breaking changes between releases. A version upgrade here is always three deliberate steps:

1. Back up the state volume (/mnt/user/appdata/deepseek-harness). From 0.1.5 upstream migrates session logs to a new format that cannot be read by older versions.
2. Reconcile plugins first. @goodandready/dsh-lanmode ≤ 0.6.8 breaks the web client on 0.1.2+ (web boot: … waiting for services: remote.*). Remove or update it before changing the tag: docker exec DeepSeek-Harness dsh plugin --profile web remove @goodandready/dsh-lanmode
3. Edit the Repository tag in the template and apply.

What changes in 0.1.2+: launch-token auth

From 0.1.2 the Web UI is gated by a one-time launch token:

• The tokened URL is printed at startup — docker logs DeepSeek-Harness.
• The token rotates on every container restart.
• Opening the URL exchanges it for a ~30-day cookie bound to the exact origin you used. Do the exchange on the hostname you actually intend to browse from (your tunnel domain, not the LAN IP), or you'll be doing it twice.
• Requests without token or cookie get dsh web authentication required.

Plugins

Plugins live in the state volume (/home/node/.dsh/profiles/web), never in the image, so image rebuilds and version bumps don't touch them. Manage them with dsh's own tooling, which works because pnpm ships in the image:

docker exec DeepSeek-Harness dsh plugin --profile web add    <package>
docker exec DeepSeek-Harness dsh plugin --profile web update <package>
docker exec DeepSeek-Harness dsh plugin --profile web remove <package>

docker exec defaults to root, which would normally leave root-owned files in the state volume and break dsh's next start. The dsh on PATH is a wrapper that re-execs as PUID:PGID for exactly that reason, so no -u flag is needed and the volume stays consistent.

On the third-party plugin question: @goodandready/dsh-lanmode exists because upstream restricts the Settings/credentials pages to loopback origins, and it removes that restriction. A quick source audit found nothing hostile, but it is unaffiliated code whose purpose is disabling a security fence in front of your API keys. The fence-preserving alternative is an SSH tunnel: ssh -L 3080:127.0.0.1:3080 root@<unraid> then http://127.0.0.1:3080.

Security model

Be clear about what this thing is: a web page that runs shell commands on the container as the agent. Everything below follows from that.

• Reachability is the perimeter. Before 0.1.2 there is no authentication; from 0.1.2 there is a launch token, but no TLS. Keep the port on a trusted LAN or behind an authenticated proxy (Cloudflare Access, Authelia). Never port-forward it to the internet.
• The trust fence is a feature. /api refuses any Host that isn't loopback or listed in --trusted-host — that is upstream's DNS-rebinding and CSRF protection. Configure it; don't work around it.
• Mount deliberately. /workspace is what the agent can read and modify. The state volume holds credentials — back it up and keep it out of anything world-readable.
• dsh runs unprivileged. No added capabilities, not privileged, nothing writable outside the mounted volume. The entrypoint does hold root for the moment it takes to chown the state volume, then setprivs down to PUID:PGID before execing dsh — the network-reachable process is never root, and nothing setuid is left behind for it to climb back through. If you would rather the container never hold root at all, pass --user 1000:1000 and keep appdata chowned yourself; the entrypoint detects that and verifies instead of repairing.
• Upstream's own safety notice still applies: dsh has not been security-audited, and its sandboxing does not guarantee isolation.

How it stays current

sync-upstream.yml runs on the Gitea Actions runners every six hours (17 */6 * * *) and on any change to the build inputs:

1. Mirror — force-syncs upstream master into this repo's master.
2. New releases — for each @deepseek-ai/dsh version npm publishes as latest or next (release candidates; alphas only when asked for) that has no tag in the registry: build, smoke-test, push. A manual run can name any exact version.
3. Freshness — reads the labels off the newest build of the pinned version and compares them to the current pnpm release, the current node:22-bookworm-slim digest, and a hash of the build recipe (Dockerfile, entrypoint, dsh wrapper, bind patch). If any moved, publishes <version>-r<run> — the path by which a security patch or an image fix reaches the pinned deployment.
4. Releases — every image tag without a v<tag> release gets one, tagged at the main commit recorded in the image's org.opencontainers.image.revision label, with digest and toolchain, the upstream release's English notes, and the caveats that apply to that version (launch token from 0.1.2, session-format migration from 0.1.5). Generated by publish-releases.js, which runs on the image's own Node base so the runner needs nothing installed.

Nothing in this pipeline can change an existing tag or publish latest. Adopting any new build — release or revision — is a template edit.

Validating a third-party image

validate-suspect-image.yml is a manual job for the question this repo started with: is that image someone handed me actually the official code? Given an image already present on the runner host's daemon, it docker creates (never runs) both it and the trusted build, exports both filesystems, and reports: config/entrypoint/labels, whether any containers use it, a byte-level diff of dsh's own code against the official release, dependency-tree drift, and red flags — patched-out 0.0.0.0 refusal, startup hooks, unexpected network callouts.

Run 2026-09-02 against runzhliu/deepseek-harness:0.1.1-rc.2: dsh byte-identical to the official release, upstream safety check intact, no tampering.

Repository layout

Branch / path	Contents
master	Exact mirror of upstream master. Never edited here.
main	This branch — the build.
Dockerfile	The image. ARG DSH_VERSION is the pinned default.
docker-entrypoint.sh	Ownership repair + privilege drop, then exec dsh "$@".
dsh-wrapper.sh	Installed as /usr/local/bin/dsh; re-execs root invocations as the runtime user.
web.cordis.patch.yml	The 0.0.0.0 bind patch, applied via --patch.
.gitea/workflows/	sync-upstream.yml (mirror · build · freshness · releases), validate-suspect-image.yml (forensics).
.gitea/scripts/	publish-releases.js — the release generator.
assets/	Logo (transparent PNG, also the Unraid template icon).

Every tag on this repo is a v<image tag> release pointing at the main commit that built the image. Upstream's source tags live on GitHub (dsh-v<version>) and are linked from each release.

License

The build tooling in this repository is MIT. DeepSeek Harness itself is MIT-licensed by DeepSeek AI; the DeepSeek name and logo belong to them and are used here to identify what the image contains.