DSH Dock
Self-hosted multi-user cloud workspaces & control plane for DeepSeek Harness (DSH).
DSH Dock (dsh-dock) provisions isolated, persistent per-user DeepSeek Harness (DSH) Agent OS development containers behind a single-port Traefik v3.7 gateway and a FastAPI + React management plane — complete with unified authentication (OIDC / local passwords & tokens), built-in plugin hosting, one-click /home/workspace backups, and agent-managed dev services.
Architecture
┌──────────────────────────────────────────────┐
│ dsh-gateway (Traefik v3.7) :9000 │
│ Single-Domain Router + ForwardAuth │
└───────┬──────────────────────────────┬───────┘
│ │
/, /admin, /my, │ │ /s/<slug>/*
/api/*, /plugins/* ▼ ▼
┌─────────────────────────┐ ┌─────────────────────────────┐
│ dsh-manager :9000 │ │ dsh-sbx-<slug> :8080 │
│ FastAPI + SQLite │ │ (no host ports exposed) │
│ React 19 Console SPA │ │ Caddy + DSH + dsh-token │
│ Built-in Plugin Registry│ │ User supervisord + cron │
└─────────────────────────┘ │ /home/workspace (persistent)│
└─────────────────────────────┘
Routing & Isolation Model
- Zero Host Port Exposure (Managed Mode): Sandbox containers join only the internal
dsh-managerDocker network and expose no host ports (18000+port sprawl is eliminated). - ForwardAuth DSH Gate: Access to
/s/<slug>/,/s/<slug>/dsh/*, and/s/<slug>/_dsh-tokenis verified centrally viadsh-manager(/api/auth/verify-sandbox/{slug}). Only the workspace owner or an active platform admin is permitted. - Open App & Preview Routes: User services exposed via
sandbox-expose(/s/<slug>/apps/<name>/) and ephemeral port forwarding (/s/<slug>/p/<port>/) stay open by default so apps can implement their own auth or webhooks cleanly.
Key Features
- Control Plane (
/admin) & Self-Service Portal (/my):- Provision and manage user sandboxes with CPU, memory, PIDs (
512),no-new-privileges, custom init scripts, Git repo bootstrapping, and reusableSandboxTemplatepresets (ships with the built-inagent-ostemplate). - Manage platform admins, local user accounts (
scryptpassword hashes) or SSO users, and encrypted LLM profiles (Fernet encryption backed bySECRET_KEY). - Live container stats, stripped ANSI logs, hot-recreation/image upgrades, and full
/home/workspacetar archive downloads (<slug>-home.tar).
- Provision and manage user sandboxes with CPU, memory, PIDs (
- Flexible Authentication (
MANAGER_AUTH_MODE):token: Zero external IdP required. Admins authenticate viaMANAGER_ADMIN_TOKEN; users sign in at/loginwith admin-provisioned passwords and can rotate their own passwords at/my.oidc: Enterprise SSO via any standard OpenID Connect provider (Keycloak, Auth0, Authentik, Okta) with optional split internal discovery (OIDC_DISCOVERY_URL).none: Trusted loopback/development mode.
- Agent-Ready Runtime Image (
dsh-sandbox):- Debian 13 (
trixie-slim), Node.js 24, Python 3.13,uv,pnpm,git,tmux,build-essential, Caddy 2,@deepseek-ai/dsh, CJK locale (zh_CN.UTF-8), WQY fonts, and corporate CA support (ca-bundle.crt). WORKDIR /home/workspaceis the default workspace and persisted home volume.- Built-in CLI helpers +
sandbox-servicesskill:sandbox-service: manage persistent user services under user-levelsupervisord.sandbox-expose: publish loopback ports at/s/<slug>/apps/<name>/via Caddy.sandbox-cron: manage persistent user crontabs surviving container restarts.
- Debian 13 (
- Modular Build-Time Toolchains (
/opt/toolchain):- Disabled by default (
INSTALL_TOOLCHAIN=false) to keep the base image lean. - Enable
INSTALL_TOOLCHAIN=trueto execute custom drop-in installers fromsandbox/toolchain/toolchain.d/*.shin sorted order into/opt/toolchain(includes10-dotnet.shas a reference).
- Disabled by default (
- Self-Hosted Plugin Index & NPM Registry:
- Mounts
plugins/directly intodsh-managerand dynamically serves/plugins/index.json, inline SVG icons,.tgzbundles (/plugins/packages/*.tgz), and read-only npm packuments (/plugins/npm/*). - Ships with
@local/dsh-plugin-file-managerand supports automatic first-boot installation viaSANDBOX_AUTO_INSTALL_PLUGINS.
- Mounts
- Mirror & Internal Network Ready:
- Supports
DOCKER_REGISTRY,APT_MIRROR(including HTTPS mirrors likehttps://mirrors.aliyun.com),NODE_MIRROR(e.g.https://mirrors.aliyun.com/nodejs-release),NPM_REGISTRY,PIP_INDEX_URL, andCUSTOM_CA_BUNDLE_PATH.
- Supports
Repository Layout
.
├── LICENSE # MIT License
├── README.md # Project overview (English)
├── README.zh-CN.md # Project overview (简体中文)
├── sandbox/ # Sandbox runtime image, supervisor, Caddy, & helpers
│ ├── Dockerfile # Parameterized sandbox image build
│ ├── docker-compose.yml # Standalone sandbox compose (publishes :8080)
│ ├── .env.example # Build args & standalone compose template
│ ├── Makefile # Convenience targets (env, build, up, logs, token, expose)
│ ├── toolchain/ # Drop-in /opt/toolchain installers (toolchain.d/*.sh)
│ ├── docs/ # Architecture, operations, OIDC, security, & troubleshooting
│ ├── tests/ # dsh-token Node tests & containerized shell script tests
│ └── rootfs/ # Entrypoint, Caddyfile renderer, supervisor, CLIs & skills
├── manager/ # FastAPI control plane, Traefik gateway, & React SPA
│ ├── app/ # Backend modules (config, db, models, docker_service, ...)
│ ├── frontend/ # React 19 + TypeScript + Vite 7 + Tailwind v4 SPA
│ ├── tests/ # Pytest unit & mock test suite
│ ├── docker-compose.yml # Traefik v3.7 gateway + dsh-manager stack
│ ├── .env.example # Control plane environment template
│ └── requirements*.txt # Runtime and dev/test Python dependencies
└── plugins/ # Hot-mounted DSH bundle plugins & index metadata
├── index.json # Discover catalog template
├── icons/ # SVG plugin icons
└── file-manager/ # Built-in Server File Manager bundle + tests
Quick Start
1. Build the Sandbox Image
cd sandbox
cp .env.example .env
docker compose build
Optional mirrors / toolchains:
docker build \ --build-arg APT_MIRROR=https://mirrors.aliyun.com \ --build-arg NODE_MIRROR=https://mirrors.aliyun.com/nodejs-release \ --build-arg NPM_REGISTRY=https://registry.npmmirror.com \ --build-arg PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ \ --build-arg INSTALL_TOOLCHAIN=true \ -t dsh-sandbox:latest ./sandbox
2. Start the Gateway & Control Plane
cd manager
cp .env.example .env
Edit manager/.env and replace the placeholders:
SECRET_KEY: generate a random secret (openssl rand -hex 32)MANAGER_ADMIN_TOKEN(forMANAGER_AUTH_MODE=token) orOIDC_*(forMANAGER_AUTH_MODE=oidc)
Launch the stack:
docker compose up -d --build
Verify and access:
- Health check:
http://localhost:9000/healthz - Admin console:
http://localhost:9000/admin - User portal:
http://localhost:9000/my - Self-hosted plugin index:
http://localhost:9000/plugins/index.json
Documentation
| Component | Documentation |
|---|---|
| Manager & Control Plane | manager/README.md |
| Sandbox Runtime | sandbox/README.md |
| Architecture & Flows | sandbox/docs/architecture.md |
| Build & Operations | sandbox/docs/operations.md |
Custom Toolchains (/opt/toolchain) |
sandbox/toolchain/README.md |
| Services & Port Exposure | sandbox/docs/services.md |
| OIDC & SSO Setup | sandbox/docs/OIDC.md |
| Security Model | sandbox/docs/security.md |
| Troubleshooting | sandbox/docs/troubleshooting.md |
| DSH Plugins | plugins/README.md |
Running Tests
Manager Backend (pytest)
cd manager
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
pytest -v
Manager Frontend (Yarn 4 + Node >= 24)
cd manager/frontend
corepack yarn install --immutable
corepack yarn typecheck
corepack yarn test
corepack yarn build
Sandbox Scripts & Helpers
# Node token helper unit tests
node --test sandbox/tests/test_dsh_token.mjs
# Toolchain installer, Caddyfile renderer (+ caddy validate), expose/cron/service CLIs
docker run --rm --entrypoint /bin/bash -v "$PWD:/repo:ro" dsh-sandbox:latest \
/repo/sandbox/tests/test_sandbox_scripts.sh /repo
DSH Plugins (file-manager)
docker run --rm --entrypoint bash -v "$PWD/plugins:/work/plugins" \
-w /work/plugins/file-manager dsh-sandbox:latest -c "node .test/run.mjs"
Contributing
Contributions are welcome! Please read the component docs before opening a pull request, preserve LF line endings on shell scripts under sandbox/, and verify all test suites pass.
License
Released under the MIT License.
No comments yet. Be the first to write one.