idsh
Dockerized DeepSeek Harness (
dsh) web UI.
Packages
| Package | Description | Version |
|---|---|---|
@idsh/mobile |
Touch CSS, Enter as a line break, and the home-screen icon | |
@idsh/privileged-ui |
The settings page over a non-loopback origin, delegating the decision to dsh | |
@idsh/remote-access |
Keeps the UI's multiplexed WebSocket alive across a stalled connection | |
@idsh/host-broker |
The host side of @idsh/host-ops: a typed, audited socket (not a dsh plugin) |
|
@idsh/host-ops |
The dsh tools that ask the host broker over a unix socket |
Documentation
The plan for the next version is in ROADMAP.md: reaching the host, the LAN and
the router, and deploying through the same channel. Phase 1 has started:
@idsh/host-broker is the host side, and
@idsh/host-ops turns that table into dsh tools.
pnpm docs:dev serves this README, ROADMAP.md, CHANGELOG.md, each package's README.md and
CHANGELOG.md, and the image's changelog; pnpm docs:build writes a static copy to dist/. The
Markdown files are the source — there is nothing to keep in sync.
Requirements
- Docker with BuildKit and Docker Compose 2.24.4+ (the channel overlays use
!reset), plus Node.js ≥24 and pnpm 12.16.1 — the pins inpackage.json— withpnpm install --frozen-lockfilerun once in the checkout.
Getting started
Provide the host uid/gid (export them, or drop them in a
.envin this directory):export UID # both shells define the real UID export GID="$(id -g)" # bash defines only UID; zsh defines GID too.envis gitignored, so it is safe to keep in the working directory.The DeepSeek API key is not an environment variable: add it once the container is up, in the web UI's settings. It is kept in the state directory, so it survives a rebuild and never reaches the image or the process environment.
Create your compose file from the template and start the development channel.
cp docker-compose.example.yml docker-compose.yml pnpm install --frozen-lockfile mkdir -p .dsh/git-broker ~/.broker-host/log # socket dir and the broker's log # the broker container needs its config and key in ~/.broker-host first: # gcb init --mode sidecar --dir ~/.broker-host ... (see the broker's README) # after `gcb authorize`, add the user.refresh mount to your own docker-compose.yml # (the stanza is in the broker overlay's header) # and its two images: the dev image copies the client from one of them (cd ../git-credential-broker && docker build --target client -t code-vaults/gcb-client:dev . \ && docker build --target host -t code-vaults/gcb-host:dev .) pnpm dev # builds :base and then :dev from this checkout GCB_IMAGE=code-vaults/gcb-host:dev docker compose -f docker-compose.yml \ -f docker-compose.broker.yml -f docker-compose.dev.yml up -d --no-buildThat is the development channel. Without the broker checkout,
Dockerfile.devtakes its client from a published image instead (--build-arg GCB_CLIENT_IMAGE=ghcr.io/code-vaults/gcb-client:<tag>), andGCB_IMAGEcan name a published broker; its config/key still come from~/.broker-host. A long-lived deployment does not build at all: it runs the pinned images fromdocker-compose.prod.yml— seepnpm deploy:prodbelow.The copy is the base;
docker-compose.broker.ymldefines the credential broker (its config, key anduser.refreshcome from~/.broker-host, see the broker's own README). A fresh checkout without that directory can still deploy: rungcb init/gcb authorizethere once, or drop the broker file and supervise the broker on the host — the file's own header says how. The channel overlay picks the images (:devhere;docker-compose.prod.ymlis the pinned production pair). Running the broker in its container is the recommended shape — one definition, one lifecycle with the deployment, and the socket shared through the state directory. A host-supervised broker is still supported: drop the broker file — and with it the IPv6 network settings it carries — bind-mount its socket directory into the container (the template already mounts the state directory,./.dsh:/home/app/.dsh, so a socket under.dsh/git-brokerneeds no extra volume) and setGIT_BROKER_SOCKETto the path inside the container (/home/app/.dsh/git-broker/broker.sock), not the host's.entrypoint.shrunsgcb setuponly when that path exists.This command is the dev channel, which is why its broker image is inline: a long-lived deployment pins both images in
.envinstead (IDSH_IMAGEandGCB_IMAGE, seedocker-compose.prod.yml), and that pin must not be mistaken for the dev channel's image.pnpm deploy:devpassescode-vaults/gcb-host:devonly whenGCB_IMAGEis unset — an exported value wins, sounset GCB_IMAGE(or set it to the dev image) if the shell carries a production pin.docker-compose.ymlitself is gitignored: it is the copy that carries your own hostnames, LAN addresses and proxy settings, which do not belong in a published repository.The template mounts only dsh's own state; add what you want (see Ports and volumes).
Grab the one-time token from the logs:
docker compose logs dsh # dsh web: http://<the address it bound>:3080/?token=... # take the token from that line; the address in it is the one inside the container, # so open it through the published port as in the next step (`--public-url` replaces # the address when set, and then the logged URL is the one to open)Open it on the Docker host (the port is published on
15080, on loopback):http://127.0.0.1:15080/?token=<token>It answers on the host only: the template binds the published port to
127.0.0.1, so reach it from a browser on that machine or through a reverse proxy there. Publishing it on every interface is the one-line change described under Ports and volumes.
The entrypoint decides what the server binds: it hands dsh this container's own address, which is
the address a published port forwards to — a listener on 127.0.0.1 inside the container cannot
receive such a connection. An explicit --host wins and DSH_BIND_HOST overrides the choice; set
DSH_BIND_HOST=127.0.0.1 to keep the server on loopback, where a published port cannot reach it and
you go through the container's own network namespace instead (docker exec, or
docker run --network container:dsh). Binding one address means every LAN address reaches the UI
once the port is published; read @idsh/remote-access's security notes
before exposing it.
The image also bakes that package into a fresh profile, where its live job is the UI's multiplexed
WebSocket: it raises the heartbeat interval so the connection survives a stall. Its 0.0.0.0
fallback for the bind is unreachable, because the entrypoint already defines the address and
0.2.1-alpha.2 and later refuse the wildcard wherever it comes from. Disabling the package — the
UI's Plugins page, or dropping it from dsh.profile.bundles — therefore no longer returns the
server to loopback; DSH_BIND_HOST is what does that. Nothing is uninstalled either way, since a
package the image declares is put back on the next start.
The token rotates on every restart.
Configuration
Environment variables (see docker-compose.example.yml):
| Variable | Purpose | Default |
|---|---|---|
PUID / PGID |
uid/gid dsh runs as (and owns bind-mounted files as); compose forwards the host's $UID/$GID |
$UID / $GID |
NPM_REGISTRY |
npm/pnpm/yarn registry: the image build and the user-level configs use it (the release build on GitHub Actions passes the official one) | https://registry.npmmirror.com/ |
DSH_TRUSTED_HOSTS |
Space-separated host authorities allowed by dsh's browser-trust fence | — |
DSH_PUBLIC_URL |
Public HTTP(S) root to advertise behind a prefix-stripping proxy; pair it with DSH_TRUSTED_HOSTS |
— |
DSH_BIND_HOST |
Concrete address dsh binds, defaulting to the container's own (the wildcard is refused): set it to 127.0.0.1 to give up remote reach, or to one address when several networks make the default ambiguous |
this container |
DSH_IPV6_SUBNET |
ULA subnet for the compose network's IPv6 half; override it when it collides with a network or route on the host, or drop the whole networks block to stay IPv4-only |
fd00:d5c0:0:1::/64 |
http_proxy / https_proxy / all_proxy / no_proxy |
Outbound proxy for dsh's HTTP requests | — |
GIT_BROKER_SOCKET |
Path of the host credential broker's socket inside the container; when it is a mounted socket, git asks the broker at push time instead of holding a token here | — |
GIT_BROKER_REQUIRE |
1 makes the helper fail closed instead of falling back to another credential helper |
— |
At boot the registry is written into ~/.npmrc, ~/.yarnrc and ~/.yarnrc.yml (corepack
and node-gyp mirrors follow), not into the environment — so a project that pins its own
registry still wins. NPM_CONFIG_REGISTRY and YARN_NPM_REGISTRY_SERVER are therefore
not read; drop them from old compose files. Variables with no default are passed through
by name, so an unset one stays unset rather than becoming empty.
Ports and volumes:
127.0.0.1:15080:3080— host port15080→ dsh's internal web server (3080), bound to loopback so only a reverse proxy on the host reaches it. Widen it to15080:3080to publish the port itself; then whatever authority that port is reached on has to be trusted by the fence../.dsh→/home/app/.dsh— dsh state and credentials (persist). This is the template's only mount.- Add the rest yourself, for example
./workspace:/home/app/Workspacesfor a workspace or./ssh:/home/app/.sshfor an ssh config. The template deliberately prescribes none. /srv/git-broker-socket:/run/git-broker— optional: the host credential broker's socket directory. It is the one mount that replaces a GitHub token in this container — see GitHub without a token in the container for why, and for the two variables that go with it.
GitHub without a token in the container
The problem
The agent works inside this container and pushes commits. That needs a GitHub credential, and every obvious way to provide it puts a standing secret where the agent can read it: a personal access token in an environment variable or a file under the state directory, an ssh key mounted for it, or credentials baked into a derived image. A long-lived token there is readable by anything the agent runs, survives after the session that needed it, has to be rotated by hand, and travels with every copy of the state directory. "The agent should not be able to do that" is not a control when the agent is the thing holding the token.
The design
git-credential-broker moves the secret out of the container:
- the broker runs on the host, holds the GitHub App's private key and the allowlist, and talks to GitHub itself;
- the container mounts only a unix socket — a path, not a secret;
gcb setup(fromentrypoint.sh, as the deployment user) records git's credential helper, and git asks the socket at push time;- the broker mints a short-lived installation token for that one push, records the request in its audit log, and hands it over; nothing is written to the container's filesystem.
So the container holds no GitHub credential at rest, and a host-side allowlist change controls
future issuance rather than sweeping every token already in flight — one that was minted stays
usable at GitHub until it expires, about an hour, which is the broker's own documented window. The
App's permissions say what a push may touch. gcb setup writes the deployment user's ~/.gitconfig and the helper's own socket/CA
files — configuration, never a credential.
The image ships the client, not a wrapper for every other tool: what an agent uses is gcb pr,
gcb gh, gcb logs and gcb run, which talk to the same socket, so the API calls it chooses to
make do not need a second credential either.
What it does not do
- It is not a sandbox: a repository the allowlist admits is one the agent can push to, and the App's permissions bound what a push can change. That is the intended boundary, not a gap.
- It does not keep a credential for anything else — it is not a secret store, and it does not cover registries, npm tokens or ssh.
- It changes nothing when the socket is not mounted:
entrypoint.shskips the setup, no helper is configured, and the deployment behaves exactly as before.
Configure it
environment:
- GIT_BROKER_SOCKET=/run/git-broker/broker.sock
- GIT_BROKER_REQUIRE=1 # fail closed instead of falling back to another helper
volumes:
- /srv/git-broker-socket:/run/git-broker
The socket is owned by the broker's user and is not world-writable, so PUID/PGID must be the
uid/gid the broker runs as — a directory ACL does not help, since access is checked on the socket
itself.
A recreate through the broker verifies what it created. Success needs compose to exit zero, the
container it created to be running with health=healthy, and — when the operation knows it —
that container to run the image it was supposed to: the built :dev, the current :dev, or a
rollback's target. A non-zero compose is a failure even if a container looks fine. On failure it restores the image that was running — the recorded one only
when nothing was — with deploy.main using the image recorded before its own build. One case is
deliberately left alone: when compose fails but the container is unchanged and healthy, nothing is
restored, because the image already running is the one a rescue would use — a tag-and-up could only
reproduce the same container. The compose file therefore has to declare a health check —
docker-compose.example.yml carries the one this deployment uses (curl, the address dsh bound,
--noproxy, and 200/401/3xx accepted — a 5xx is not an answer that proves it is up). A container with no health status at
all counts as failed, and the reason is written to the broker's compose.log.
docker exec -u app dsh gcb probe --repo owner/repo answers the
broker's decision — exit 0 allowed, 1 denied, 3 unreachable — with the credential reduced to a
fingerprint, so its output is safe to share.
gcb setup also rewrites git@github.com: remotes to https inside the container only — the
host's ssh workflow is untouched — so a deployment that mounts its own ssh key loses the ssh remote
form there.
For development, the dev image carries the broker's local client build
(code-vaults/gcb-client:dev, built from that checkout), and docker-compose.broker.yml defines the
broker as the gcb service (its image comes from GCB_IMAGE: code-vaults/gcb-host:dev from that
checkout here, or a pinned sha-<commit>/<version> for a long-lived deployment), against the same socket directory
(.dsh/git-broker — created once by hand, mkdir -p .dsh/git-broker, together with the broker's
own log directory; the pre-flight refuses to remove the deployment when either is missing), and
dsh waits for its socket to be bound — the service's healthcheck is
test -S /run/git-broker/broker.sock, and depends_on uses service_healthy. One broker serves the host, so it
replaces a standalone deployment rather than being added next to one; when the broker is supervised
elsewhere, drop the service and dsh's depends_on entry — compose refuses a dependency on a
service that is not defined.
Releasing
The companion packages under packages/ are released with
changesets. A pull request that changes one carries a changeset
(pnpm changeset); merging it to main lets the Release
workflow collect every pending changeset into one "Version Packages" pull request, and merging
that publishes the bumped packages to npm. The version field in a package's manifest is an
output of that flow, not something to edit by hand.
What the images bake moves with that release: pnpm run version runs
tools/sync-image-pins.mts, so the version pull request bumps the
dsh plugin … lines in Dockerfile to the versions it is releasing. The image keeps a version of its
own in image/, a private package that only carries it, and a release that changes what
the image bakes bumps it in one of its changesets — CI refuses a release where none does. When that
version moves, the workflow builds the image and pushes it to ghcr.io/devockr/idsh and to
devockr/idsh on Docker Hub as :latest, :sha-<commit> and :<version>, so a deployment can pull
it instead of building. pnpm deploy:prod (pnpm deploy:prod:dry first) deploys the pins from
docker-compose.prod.yml — IDSH_IMAGE and GCB_IMAGE, read from
the shell or the deployment's .env — pulling them and verifying the container it created runs
that image and is healthy. It never builds: the image is the one a release published, and the
published stage installs its plugins strictly, so it cannot exist while one of them is
unpublished. Until they are, the path is pnpm deploy:dev, which builds from packages/. GHCR creates every new package private: it inherits the linked
repository's permissions, not its visibility. So flip idsh to public once (package settings, then
Danger Zone — it cannot be made private again), or pull with a token. Docker Hub needs neither: a
repository there is public by default.
The package page lists unknown/unknown rows beside amd64 and arm64: those are the build's
provenance and SBOM attestations, written into the same manifest list with no platform of their own.
They are what lets a digest be traced back to the commit and workflow that produced it.
Notes
- Runs as your host user — the container starts as root, re-points its
appaccount toPUID/PGID, fixes ownership of the home skeleton (leaving bind mounts alone), then drops privileges withsetpriv. Files in the mounts are owned by you, not a container uid. - One-off commands —
docker execlands as root; usedocker exec -u app …for a shell as the working user, ordocker exec dsh dsh …for arbitrary dsh invocations. Extradocker run <image> <args>are appended after dsh's web flags, so they can't override--profile web. - Sandbox — dsh's file sandbox needs user namespaces or Landlock. On hosts without them (e.g. Synology's 4.4 kernel), either set
DSH_PERMISSION_MODE=danger-full-access, or approve thedanger-full-accessescalation when prompted in the UI. - Plugins — the image bakes a profile when it is built: dsh's own
webtemplate plus its companion packages —@idsh/remote-access,@idsh/privileged-ui(the settings page over the LAN, which the image used tosedinto dsh) and@idsh/mobile(the touch CSS, Enter as a line break, and the home-screen icon) — installed from npm by name (the dev image, what we run locally, bakes this checkout'spackages/aslink:s instead). A deployment without a profile starts from that one; an existing profile keeps those packages at the version the image declares — compared by each package's ownpackage.json— putting back anything missing, broken or below it, exactly as the image installed it (a link in the dev image, where a built checkout mounted at/opt/dsh/packagesis what runs — edit, rebuild, restart; files otherwise). Anything at that version or above is left alone, which is where a pinned version or a fork lives, and a package is turned off by dropping it from the bundle list (the UI's Plugins page), not by uninstalling it. Plugins live in the.dshmount and survive recreations. - UI probe —
node tools/dev/ui-probe.mtsboots a throwaway instance in an isolated$DSH_HOMEand drives it with a real browser, so a client plugin's runtime behaviour can be checked without touching the live profile. It installs the plugin set the image baked — what a deployment gets — and--install <pnpm-spec>adds to or replaces that, which is how a checkout or a candidate package is probed;--barestarts from the shipped template alone, for narrowing down which plugin is at fault. It needs the:devimage —pnpm devbuilds it from a checkout, anddocker-compose.dev.ymlcarries the browser settings it reads, which needs Compose 2.24.4+ for its!resettag — which is the one carrying the browser libraries;--no-browserskips the browser and checks the served boot graph instead. - Remote exposure — what reaches the UI is the address the entrypoint binds and the port you publish: a published port forwards to that address, and the bind also puts it into dsh's browser-trust fence. Put TLS and auth (or a VPN) in front unless that network is trusted; see
@idsh/remote-access's README for what the package itself does. - HTTPS reverse proxy — if you front this with nginx, keep the
Hostheader intact (proxy_set_header Host $http_host;) so the browser-trust fence passes, and add WebSocket upgrade headers.
Sponsors and Backers
Sponsors
| 1stG | RxTS | UnTS |
|---|---|---|
Backers
| 1stG | RxTS | UnTS |
|---|---|---|
No comments yet. Be the first to write one.