@codebam/dsh-opensandbox
在 OpenSandbox 容器中运行 DeepSeek Harness 命令执行：为 dsh 提供由 OpenSandbox 支持的 ctx.subprocess 和容器世界中的 ctx.sandbox。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add @codebam/dsh-opensandbox@0.2.2Opensandbox 以 @codebam/dsh-opensandbox 发布，当前版本为 0.2.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Run the DeepSeek Harness (dsh) execution world inside
OpenSandbox containers.
The plugin registers three dsh services:
| Service | Replacement | Effect |
|---|---|---|
ctx.subprocess | @deepseek-ai/dsh-subprocess-local | Commands and PTY shells run through OpenSandbox execd. |
ctx.sandbox | @deepseek-ai/dsh-sandbox-local | Reports the container world's confinement facts to dsh's stock sandbox-aware consumers. |
ctx.fs | @deepseek-ai/dsh-fs-sandbox | Host filesystem backend fenced by the same mount table: file tools read and write only under the configured sandbox mounts, plus explicit harness read paths. |
The package is itself a dsh profile bundle (dsh.bundle.patch points at its cordis.patch.yml),
so the Web Plugins page can install it and switch the whole world on and off; the bundle layer
disables the three rows above that it replaces. See Install.
Because ctx.subprocess is the shared execution seam, these existing dsh plugins keep working
over the container world without code changes:
@deepseek-ai/dsh-bash-sandbox — the model-facing bash tool@deepseek-ai/dsh-terminal-bash — persistent PTY sessions (bash)@deepseek-ai/dsh-tool-fs-search — grep/glob run inside the sandboxsandbox:policy contextThe session's immutable workspace is bind-mounted into the sandbox at the same absolute path, so
the container and ctx.fs see the same files. This is the key difference from a single-project
plugin: dsh web sessions can open any project directory under a configured workspaceParents
root, and each session gets its own sandbox mounted with that exact workspace root. The
configured workspaceRoot remains the fallback for calls without a session cwd.
The filesystem backend is host-side, but the plugin fences it with the session workspace and the
same mount table the container uses: a model-facing read, write, or edit cannot resolve a
path outside the session workspace, the configured mounts, or the narrow trustedReadPaths list
(used for harness-owned reads such as user skills and ~/.dsh/AGENTS.md). Context-free harness
discovery may read under workspaceParents (minus protectedPaths); it cannot turn one of those
directories into a bind mount. Command execution is still the kernel boundary; the filesystem
fence is the policy boundary that keeps the model's file tools from escaping the session
workspace and mount table.
Node.js >= 20 (dsh bundles a newer Node).
A reachable OpenSandbox lifecycle server with the Docker runtime.
The OpenSandbox server must allow-list the host paths you mount. In its TOML:
[storage]
allowed_host_paths = ["/home/your-user", "/persistent", "/tmp", "/nix/store"]
The sandbox image must contain /bin/sh and a sleep that accepts infinity
(debian:*, ubuntu:*, python:* and similar images do).
spawnTerminal needs a WebSocket to execd, so this plugin asks the lifecycle
API for each sandbox's direct published endpoint (the official SDK default,
use_server_proxy=false) instead of routing through the server's own proxy.
That is deliberate: in the stock server image the API-proxy WebSocket route
never completes its handshake to the sandbox and then crashes while reporting
that failure on a websockets API mismatch. A deployment where the client
cannot reach the sandbox's published port directly is not supported.confine() reports partial
enforcement for confined modes because read-only/workspace-only semantics are not re-expressed
per command. The ctx.fs fence applies the mount table to file-tool targets instead.[storage] allowed_host_paths); a command cwd outside the session workspace and mount table
fails before any sandbox is created rather than falling back to the host.workspaceParents deliberately grants context-free harness reads (and the ability to open a
dsh session) under those roots. Keep the list narrow, and put credential trees in
protectedPaths. A session workspace that contains a protected path is refused.extraWritableMounts and /directory-add <path> rw are host-operator grants. The workspace is
read-write by default; every other path is read-only unless a human explicitly says otherwise.danger-full-access escalation cannot widen the mount table. It can lift dsh's session
policy, but a read-only mount stays read-only and a path outside the table stays denied.The package declares a dsh profile bundle (dsh.bundle.patch), so it can be installed and
switched from the Web sidebar's Plugins page:
dsh plugin --profile dsh-tui add @codebam/dsh-opensandbox
The same install is Add plugin on the Plugins page, where the spec may be the package name,
a version range, or the absolute path of this checkout. The installed bundle gets the page's
on/off switch, and the bundle's own page gets the opensandbox-world row switch. The bundle
layer disables the subprocess, sandbox, and fs-sandbox rows itself, so switching the
bundle off restores dsh's built-in execution world with no second edit. Use the bundle switch,
not the opensandbox-world row switch, for that transition: the row switch unmounts only the
plugin and leaves the layer's built-in providers disabled. Enablement is stored in
the profile: the bundle list in its package.json and disabled overrides in its
cordis.patch.yml. A profile whose files are deployment-managed (Nix, home-manager, a
read-only profile tree) can still carry the plugin patch by hand; the page then shows
opensandbox-world in its read-only inventory but has no bundle row to switch. Do not mix the
two forms in one profile: a second insert of opensandbox-world, or a row whose name differs
from @codebam/dsh-opensandbox, leaves the composed tree with a duplicate or mismatched row that
the Plugins page will not switch.
A hand-managed profile installs the package with npm instead:
npm install @codebam/dsh-opensandbox
dsh provides the @deepseek-ai/* peer packages at runtime, so they are marked optional and are
not fetched from npm by this package.
Connection, image, and mount-table values are host facts, so the bundled layer inserts the row
without configuration. With the bundle installed, put the deployment's values in the profile's
own cordis.patch.yml, which is applied after every bundle layer; the id-targeted override below
wins over the row the bundle inserted:
- id: opensandbox-world
config:
# Connection (or set OPEN_SANDBOX_API_KEY / OPEN_SANDBOX_DOMAIN in dsh's environment).
apiKeyFile: /run/user/1000/opensandbox/api-key
domain: 127.0.0.1:8090
# Sandbox image and workspace.
image: docker.io/library/debian:bookworm-slim
workspaceRoot: /home/your-user/project
# Host directories that are part of the reviewed boundary. Use
# extraWritableMounts only when the agent must write there; it is a
# host-operator-only grant.
extraReadOnlyMounts:
- /nix/store
extraWritableMounts: []
# Harness-owned host reads (user skills, ~/.dsh/AGENTS.md). Keep this
# list narrow: every entry is reachable by the model-facing read tool.
trustedReadPaths:
- /home/your-user/.dsh/AGENTS.md
- /home/your-user/.dsh/skills
# dsh web sessions may open any project under these roots; each
# session still binds only its own workspace root into its sandbox.
workspaceParents:
- /home/your-user/Documents/git
# Credential/control trees ctx.fs must not read and the server guard
# must not allow mounting a parent of.
protectedPaths:
- /home/your-user/.ssh
- /home/your-user/.gnupg
- /home/your-user/.dsh
- /home/your-user/.config/gh
- /home/your-user/.config/sops
# Limits and lifetime.
timeoutSeconds: 43200
cpu: "4"
memory: 8Gi
A profile that does not install the bundle performs the row swap in cordis.patch.yml itself.
Disable the two local providers and the host-fs backend, then insert the row and copy the fields
from the config: mapping above under the inserted row:
- id: subprocess
disabled: true
- id: sandbox
disabled: true
# The shipped fs backend fences writes but leaves reads unconfined.
- id: fs-sandbox
disabled: true
- insert:
- id: opensandbox-world
name: '@codebam/dsh-opensandbox'
config:
# … the config mapping shown above
Relative name values resolve from dsh's profile node_modules, where
npm install @codebam/dsh-opensandbox places the package. An absolute path to index.mjs
also works, but a path-named row is outside the bundle inventory and stays read-only in the
Plugins page.
A Nix or home-manager deployment can keep owning the profile's cordis.patch.yml and still use
the bundle: install the package once with dsh plugin --profile <name> add ... (or list it in the
profile's package.json dependencies and dsh.profile.bundles), remove the hand-written row swap
from the managed patch, and keep only id-targeted overrides there for host configuration and
environment-conditional enablement. The bundle selection then lives in package.json, while the
managed patch still wins for config and can preserve a per-process escape hatch. A row switch
on the bundle's page also records its disabled override in that patch, so a deployment that
rewrites the file reasserts its own default on the next activation; the bundle switch itself
lives in package.json. A Nix package of this plugin must install cordis.patch.yml next to
index.mjs; the npm files list is the contract for what ships.
- id: subprocess
disabled: !!js "!process.env.DSH_NO_OPENSANDBOX"
- id: sandbox
disabled: !!js "!process.env.DSH_NO_OPENSANDBOX"
- id: fs-sandbox
disabled: !!js "!process.env.DSH_NO_OPENSANDBOX"
- id: opensandbox-world
disabled: !!js "Boolean(process.env.DSH_NO_OPENSANDBOX)"
config:
# … the config mapping shown above
| Field | Default | Meaning |
|---|---|---|
apiKey | OPEN_SANDBOX_API_KEY | Lifecycle/execd API key. |
apiKeyFile | OPEN_SANDBOX_API_KEY_FILE | File holding the API key; read at startup. |
domain | OPEN_SANDBOX_DOMAIN or localhost:8080 | Lifecycle host, optionally with port. |
protocol | OPEN_SANDBOX_PROTOCOL or http | http or https. |
image | docker.io/library/debian:bookworm-slim | Sandbox image URI. Pin a digest in production. |
workspaceRoot | process.cwd() | Host directory mounted read-write at the same path. |
extraReadOnlyMounts | ["/nix/store"] | Extra host dirs mounted read-only at the same path. An empty list means this default, because the loader materializes an absent optional array as []. |
extraWritableMounts | [] | Host dirs mounted read-write at the same path. Host-operator-only: never source this from model output or an untrusted file. |
trustedReadPaths | [] | Host paths ctx.fs may read for harness-owned features (skills, user instructions) without mounting them into the container and without allowing writes. |
workspaceParents | [] | Host directories under which a dsh session may open a project (for example a code root). They authorise a session workspace but are never bind-mounted themselves, so a sibling project cannot become a model workdir mount. |
protectedPaths | [] | Host credential/control trees that must stay hidden from ctx.fs unless a trusted read path explicitly covers them. The OpenSandbox server guard should name the same paths to reject bind mounts of their parents. |
allowDynamicMounts | true | Offer the human , , and commands. The added mounts live only in this dsh process. |
workspaceRoot/workspaceParents, must not contain a protectedPaths entry, and must not overlap a configured mount. The model may choose a workdir only inside that session workspace or a configured mount; sibling directories under a workspace parent are rejected as bind roots.codebam.dsh.workspace).PATH is the host PATH restricted to directories a mount makes visible, plus
/run/current-system/sw/bin, /etc/profiles/per-user/$USER/bin and ~/.nix-profile/bin when
they exist. That fallback matters because a dsh started by a systemd user unit inherits systemd's
minimal PATH, which carries no /nix/store entries at all.danger-full-access still runs in the OpenSandbox world; the plugin never falls back to host
execution.enforcement: "partial", because the container bounds host file effects
but does not re-express workspace-only/read-only semantics inside the container. The ctx.fs
fence applies the mount table to the model's file tools instead.nix build cannot add paths from inside the sandbox. Host builds,
signed commits, and pushes are separate grants, not defaults./directory-add <absolute-host-path> [ro|rw] is a human slash command, not a model tool: the
command registry runs it directly in the interactive UI and never sends it to the model. It mounts
an existing host directory at the same absolute path inside the sandbox, read-only by default;
rw is an explicit read-write grant. Existing sandboxes are recycled, so the next command starts
from the new boundary. A path that is already visible through a configured mount is rejected
instead of being nested or shadowed.
/directory-list prints the effective mount table and /directory-remove <path> removes a
runtime-added mount. Mounts added this way are in-memory only: they disappear when dsh exits, so a
restart returns to the profile's reviewed configuration.
Those capabilities are not enabled by default. If you grant them, you are widening the sandbox boundary to include the host Nix daemon and/or host credentials:
/etc/nix and /nix/var/nix/daemon-socket mounted read-only. The container's
nix then talks to the host daemon, which owns the store and builds unsandboxed from the
agent's point of view; treat that as granting host build authority.GH_TOKEN only if gh should act as you.Prefer an explicit human-launched elevated session (or /directory-add on exact directories) over
making any of these grants the default for ordinary agent sessions.
npm run check
npm pack --dry-run
npm publish --access public
The package name is scoped and publishConfig.access is public, so the explicit flag is only a
reminder.
npm install
npm run check
There is no build step: the published files are the same ESM files dsh loads.
npm test runs the mount-policy/filesystem fence tests, asserts the profile-bundle manifest and
cordis.patch.yml through dsh's own overlay parser, and runs a mock E2E over an in-process fake
OpenSandbox server (it asserts the execd request schema, SSE framing, metadata labels, mount
modes, and PTY frames). The tests import dsh runtime modules, which npm cannot fetch, so point
the checkout at any dsh install's modules first:
ln -sfn "$DSH_HOME/profiles/node_modules" node_modules # DSH_HOME defaults to ~/.dsh
npm test
MIT
OpenSandbox and DeepSeek Harness are separate projects with their own licenses. This plugin talks to OpenSandbox over its HTTP/WebSocket APIs and mounts the dsh capability seams provided by the harness.
/directory-add/directory-remove/directory-listprovideFilesystem | true | Mount the plugin's mount-fenced ctx.fs. Set false only if another trusted provider supplies ctx.fs; the shipped dsh-fs-sandbox leaves reads unconfined. |
timeoutSeconds | 43200 | Sandbox TTL; the server minimum is 60. The cached sandbox is revalidated before each command, so a server-reaped sandbox is replaced instead of leaving commands on a dead endpoint. |
requestTimeoutMs | 300000 | Lifecycle HTTP timeout. |
sandboxWaitMs | 180000 | Max wait for a new sandbox to report Running. |
commandTimeoutMs | 0 (disabled) | Optional execd-side per-command timeout. |
cpu / memory | "4" / "8Gi" | Container resource limits. |
home | /root | Container HOME. |
env | {} | Extra environment variables for every sandbox command. Wins over forwardEnv. |
forwardEnv | [] | Host environment variable names to forward into the sandbox (GH_TOKEN, SSH_AUTH_SOCK). Unset names are skipped, not blanked. |