- JavaScript 80.8%
- Python 11.8%
- Shell 6.8%
- Dockerfile 0.6%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
A dependency-free Node portal that authenticates against an OIDC provider (Zitadel), provisions a DeepSeek Harness container per account on first sign-in, proxies the browser to it, and offers read-only conversation sharing between users. This is a genericised copy of a working homelab deployment: hostnames, mesh addresses, filesystem paths, service names, OIDC client ids and policy ids were replaced with placeholders, and all credentials — including SSH private keys — were removed. Some operational scripts are retained as worked examples of that deployment. Verified after genericisation: every JavaScript and Python source parses, all shell scripts pass bash -n, and test/podman-path.mjs passes 18/18, matching the original unmodified tree. |
||
| container | ||
| deploy | ||
| portal | ||
| test | ||
| tools | ||
| .env.example | ||
| .gitignore | ||
| README.md | ||
dsh-portal — SSO portal with one DeepSeek Harness container per user
A small, dependency-free portal that gives every account in an OIDC tenant its own DeepSeek Harness (DSH) instance — provisioned on first sign-in — plus read-only conversation sharing between users.
Why this shape
DSH is deliberately single-operator: there is no user registry, no per-peer
filtering, and the filesystem sandbox fences writes only (reads, listings and
GET /api/file?path=… are unrestricted). Credentials cannot be hidden from the
agent either, because the agent's tools run as the same OS user. A plugin can
therefore only ever partition views, never enforce a boundary.
So per-account isolation has to come from deployment isolation. One container
per account — with its own $DSH_HOME, workspace volume, uid and network — is the
only kernel-enforced boundary available. That is what this portal automates.
Architecture
browser ──TLS──▶ reverse proxy ──▶ portal (Node, :8899)
│ OIDC Authorization Code + PKCE → Zitadel
│ session cookie (host-only, HttpOnly)
│
├─ provisions a container per user (podman)
├─ holds that container's DSH launch token
│ server-side and proxies requests to it
└─ serves /_portal/* (status, sessions, share)
│
▼ private podman network, no host publish
dsh web inside the user's container
Design decisions worth knowing:
- Single hostname. One public hostname serves the portal and every user's harness; the portal session decides which container a request belongs to. This avoids wildcard DNS, a wildcard certificate and a wildcard edge rule.
- The browser never holds a container credential. The portal exchanges each container's DSH launch token for that container's cookie and keeps it server-side; the browser only holds the portal's own cookie.
- Containers publish nothing to the host. A rootful
podmanpublish on0.0.0.0is internet-facing regardless of the host firewall, so user containers are reachable only over a private podman network. The portal talks to them there, or over a loopback port in process mode. - Process mode (
RUNTIME=process) runs each user'sdsh webdirectly on the host instead of in a container. Useful for development and for the test suite; it is not an isolation boundary.
Requirements
- Node.js ≥ 22.15 (the portal and all tooling use built-in modules only)
podmanfor container mode (rootful or rootless)- A DSH image, e.g.
localhost/deepseek-harness:0.2.0-rc.2 - An OIDC provider — Zitadel is what this was built and verified against
- A TLS-terminating reverse proxy (the portal serves plain HTTP and expects one)
Install
-
Configure. Copy the template and fill in the two values from your IdP:
sudo mkdir -p /etc/dsh-portal sudo cp .env.example /etc/dsh-portal/portal.env sudo chmod 600 /etc/dsh-portal/portal.env sudoedit /etc/dsh-portal/portal.env # OIDC_ISSUER, OIDC_CLIENT_IDIn Zitadel: Project → Application → Web, Authorization Code + PKCE, redirect URI
https://<your-host>/_portal/auth/callback. LeaveOIDC_CLIENT_SECRETempty for a public PKCE client. -
Preflight the OIDC configuration before deploying — it validates the issuer, discovery document, JWKS, PKCE support and the client id, and prints the exact redirect URI to register:
sudo node deploy/check-oidc.mjs /etc/dsh-portal/portal.env -
Install (installs the systemd unit, copies the portal to
/opt/dsh-portaland starts the service):sudo ./deploy/install-portal.shTo install onto a remote host, use the bundled ssh2-based deployer — this container has no
sshbinary, and the same helper is used for Forgejo:DEPLOY_HOST=<host> DEPLOY_PORT=22 DEPLOY_USER=root \ node deploy/deploy-via-ssh.mjs --check # connectivity + tooling DEPLOY_HOST=<host> DEPLOY_USER=root \ node deploy/deploy-via-ssh.mjs # installKeys default to
keys/portal_rsa(target) andkeys/docs_rsa(jump host). Generate your own — no keys are shipped in this repository. -
Add the edge route so your reverse proxy forwards the public hostname to the portal.
deploy/edge_add_dsh_route.pyis an example that drives an HAProxy-based edge (dry-run by default):python3 deploy/edge_add_dsh_route.py # dry run python3 deploy/edge_add_dsh_route.py --applyLeave the edge's own SSO gate disabled for this hostname: the portal performs the OIDC dance itself, and a second gate would break the redirect.
Configuration
All configuration lives in one env file (/etc/dsh-portal/portal.env); see
.env.example for the annotated list. The ones that matter:
| Variable | Meaning |
|---|---|
OIDC_ISSUER, OIDC_CLIENT_ID |
Your IdP. OIDC_CLIENT_SECRET stays empty for a public PKCE client. |
PORTAL_BASE_URL, APP_DOMAIN |
The single public hostname. APP_DOMAIN must equal its host. |
PORTAL_BIND, PORTAL_PORT |
Where the portal listens. Never 0.0.0.0 on a rootful host. |
RUNTIME |
podman (isolation) or process (development). |
DSH_IMAGE, DSH_NETWORK, DSH_INTERNAL_PORT |
Container-mode settings. |
DSH_HOME_MOUNT, DSH_WORKSPACE_MOUNT |
Per-user volumes: sessions, memory, credentials, project files. |
DSH_PATCH_FILE |
Cordis patch applied to every container (e.g. bind the webserver inside the container). |
DSH_EXTRA_MOUNTS |
Extra read-only bind mounts, for vendored plugins. |
ALLOWED_EMAIL_DOMAINS, ADMIN_EMAILS |
Empty = any account on the tenant gets a container. |
AUTO_PROVISION, SHARE_REQUIRE_LOGIN, INJECT_SHARE_BUTTON |
Behaviour switches. |
SESSION_MAX_AGE_DAYS |
Portal session lifetime. |
COOKIE_SECRET |
Leave unset to auto-generate and persist under DATA_DIR. |
Conversation sharing
Sharing is a snapshot, never a live session — DSH keeps one write handle per session and has no cross-process coordination, so two people cannot drive one conversation.
- Preferred: a Share conversation control injected into the harness page.
- Fallback: the same action from the portal page.
- Recipients get an immutable read-only transcript; the owner can revoke it; links expire after 30 days.
Be clear-eyed about what a shared transcript contains: a DSH session log is everything the agent observed — file contents, command output, diffs, uploads. Sharing a conversation shares all of it. Provider credentials never enter logs, but tool output can contain arbitrary secrets, so treat published sessions as sensitive.
Operations
- Health:
GET /healthz→{"ok":true,"users":N}. - Containers survive portal restarts. The unit sets
KillMode=process; without it, systemd's defaultcontrol-groupSIGTERMs every user container when the portal restarts. - A restarted container mints a new DSH launch token. The portal detects the
resulting
401, re-reads the newest token from the container's logs and retries once. - A dead container used to mean permanent 502s because the backend cookie was cached; the portal now drops the cached cookie on an upstream error, so the next request re-provisions.
podman restartcan fail on containers created by a process that has since exited (netavark: setns: IO error: Invalid argument). Recreate instead (podman rm -fplus a re-provision); the user's volumes are untouched.- Upgrades: re-run
deploy/install-portal.sh. It keeps an existingportal.env, so apply mount or env changes there by hand too.
Security model — and what this does not do
What it gives you:
- A real, kernel-enforced boundary per account: separate container, uid,
$DSH_HOME, workspace volume and network namespace. - One authentication boundary for the browser, with the container credentials held server-side.
- Containers that publish no ports to the host.
What it does not do:
- No per-user resource quotas. Containers have no CPU or memory limits.
- No self-service account management. Access == having an account on the tenant.
- The portal is privileged by design — it holds every container's launch
token and cookie in memory. Treat it as a trusted component and protect
portal.env(mode0600). - No redaction pass on shared transcripts.
- Not multi-tenant-hardened in the "mutually hostile users" sense beyond the container boundary itself.
Testing
node test/podman-path.mjs # container backend against a stubbed podman CLI (18 checks)
node test/e2e.mjs # real OIDC flow via a mock IdP + real dsh web (29 checks)
node test/jump-host.mjs # ssh2 jump-host path
node test/check-oidc.mjs # OIDC preflight against a mock issuer
test/e2e.mjs needs the dsh binary on PATH; test/podman-path.mjs needs no
podman at all (the CLI is stubbed).
Two environment quirks are worth knowing when running the suites in a container:
Node's HTTP client sends no accept-encoding, so a plain-HTTP test never sees
the harness's gzip path; and this container cannot signal processes it did not
start, so a crashed run can leave dsh web servers behind that poison the next
run. Run the suites on a host where you can clean up.
File map
| Path | What it is |
|---|---|
portal/src/server.js |
HTTP server, routing, auth gate, share endpoints |
portal/src/oidc.js |
OIDC discovery, PKCE, token exchange, ID-token verification |
portal/src/runtime.js |
Container/process lifecycle, launch-token handling |
portal/src/proxy.js |
Request proxying into the user's harness, incl. WebSocket upgrade |
portal/src/sessions.js |
Session listing and share creation/revocation |
portal/src/store.js |
JSON store for users, sessions and shares |
portal/src/core.js |
Config, logging, small helpers |
container/ |
Image build, entrypoint and the cordis patch applied to every container |
deploy/ |
Installer, systemd unit, OIDC preflight, remote deployer, example edge/IdP/NetBird helpers |
test/ |
Test suites and mock IdP |
tools/ |
ssh2-based ssh, git-ssh and remote-run helpers (this project ships no ssh binary) |
Provenance and genericisation
This is a genericised copy of a working homelab deployment. Hostnames, mesh
addresses, paths, service names, OIDC client ids and policy ids have been
replaced with placeholders (example.com, 100.64.0.10, /opt/dsh-portal, …),
and all credentials — including SSH private keys — were removed. Some operational
scripts are retained as worked examples of that deployment; treat them as
examples rather than portable tooling.
Verified after genericisation: all JavaScript and Python sources parse, the shell
scripts pass bash -n, and test/podman-path.mjs passes 18/18 — the same result
as the original, unmodified tree.
License
MIT.