No description
  • JavaScript 80.8%
  • Python 11.8%
  • Shell 6.8%
  • Dockerfile 0.6%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Yarrith Devos 4fd22bd117 Initial import: SSO portal with one DeepSeek Harness container per user
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.
2026-10-12 14:02:09 +00:00
container Initial import: SSO portal with one DeepSeek Harness container per user 2026-10-12 14:02:09 +00:00
deploy Initial import: SSO portal with one DeepSeek Harness container per user 2026-10-12 14:02:09 +00:00
portal Initial import: SSO portal with one DeepSeek Harness container per user 2026-10-12 14:02:09 +00:00
test Initial import: SSO portal with one DeepSeek Harness container per user 2026-10-12 14:02:09 +00:00
tools Initial import: SSO portal with one DeepSeek Harness container per user 2026-10-12 14:02:09 +00:00
.env.example Initial import: SSO portal with one DeepSeek Harness container per user 2026-10-12 14:02:09 +00:00
.gitignore Initial import: SSO portal with one DeepSeek Harness container per user 2026-10-12 14:02:09 +00:00
README.md Initial import: SSO portal with one DeepSeek Harness container per user 2026-10-12 14:02:09 +00:00

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 podman publish on 0.0.0.0 is 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's dsh web directly 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)
  • podman for 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

  1. 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_ID
    

    In Zitadel: Project → Application → Web, Authorization Code + PKCE, redirect URI https://<your-host>/_portal/auth/callback. Leave OIDC_CLIENT_SECRET empty for a public PKCE client.

  2. 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
    
  3. Install (installs the systemd unit, copies the portal to /opt/dsh-portal and starts the service):

    sudo ./deploy/install-portal.sh
    

    To install onto a remote host, use the bundled ssh2-based deployer — this container has no ssh binary, 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             # install
    

    Keys default to keys/portal_rsa (target) and keys/docs_rsa (jump host). Generate your own — no keys are shipped in this repository.

  4. Add the edge route so your reverse proxy forwards the public hostname to the portal. deploy/edge_add_dsh_route.py is 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 --apply
    

    Leave 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 default control-group SIGTERMs 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 restart can fail on containers created by a process that has since exited (netavark: setns: IO error: Invalid argument). Recreate instead (podman rm -f plus a re-provision); the user's volumes are untouched.
  • Upgrades: re-run deploy/install-portal.sh. It keeps an existing portal.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 (mode 0600).
  • 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.