DSH plugin sandbox: three DeepSeek Harness sandbox modes
DeepSeek Harness's dsh-sandbox governs file-system effects through SandboxMode, which has three tiers: read-only, workspace-write and danger-full-access — no writes, writes confined to the workspace, and no restriction; network and process visibility are outside this sandbox's scope (source). The reason a sandbox exists is direct: since the model can make commands actually run through tools, there must be a boundary limiting what they can touch once running. This piece covers what the three tiers are, where the boundary lies and how to choose; the plugin permission boundary is in DSH plugin capabilities and permission boundary, and command-execution errors in fixing sandbox escalation errors.
Why a sandbox is needed: drawing a boundary around execution
The model cannot touch files by itself, but it can request command execution through tools — once a command runs, side effects happen on your machine, and the sandbox is the file-system boundary drawn around that execution path (source). Lay out the chain:
- The ability comes from tools: the model can run commands because some tool turns a request into a real process; without tools it could not even request execution.
- Side effects come from real processes: a command reads and writes the real file system when it runs, so the constraint must land on the execution side rather than rely on the model's goodwill.
- The constraint must be tiered: tasks differ widely in how much writing they need — some only read, some change files inside the project, a few truly need full-disk rights; a single switch is neither safe nor usable.
- Tiers give a predictable default: with three clear tiers, you can start from the tightest and widen only when needed, instead of facing an all-or-nothing choice every time.
The three SandboxMode tiers in DeepSeek Harness
DeepSeek Harness's SandboxMode has three tiers — read-only, workspace-write and danger-full-access — and the tier decides how far an execution's writes are restricted (source). Taken one by one:
read-only: no writes allowed, execution can only read. Suited to "look but do not change", such as retrieval, analysis and report generation.workspace-write: writes allowed but confined to the workspace directory. This is the everyday middle tier — the task can really produce files without spreading changes outside the project.danger-full-access: no file-system restriction at this layer, the strongest and most careful tier. Thedangerin the name is not decoration: execution may write anywhere.
The tiers form a ladder from tight to loose: the wider the ability, the more likely it is to trigger approval when needed — which is why "escalation" exists.
It governs file-system effects only
DeepSeek Harness's sandbox governs file-system effects only; network and process visibility are outside its scope (source). This boundary must be stated, or the protection is easily overestimated:
- It governs write-like side effects: it constrains which files an execution touches, the main target of isolation and the actual meaning of the
read-onlyandworkspace-writetiers. - Network access is not its job: whether a command can reach the network, and where, is outside this sandbox and needs separate assessment.
- Process visibility is not its job either: which other processes on the machine a command can see is likewise out of scope.
- So do not treat "a sandbox is on" as blanket insurance: it is a boundary in the file-system dimension, and other dimensions have their own mechanisms.
How tiers are triggered: approval and escalation
A tier is not only a setting: it is validated at execution time — when a call requests wider permission than the current mode, approval handling is triggered (source). Three points:
- Validated before execution: the execution carries the tier intent it requires, and the system checks it against the currently allowed range.
- Crossing triggers approval: a request for wider permission is not silently allowed but goes down the approval path for a human to decide.
- Escalation must be "wider": escalation only makes sense when it moves in the direction of loosening; the related errors are in fixing sandbox escalation errors.
Per-platform backends and consumers
DeepSeek Harness local sandbox backends differ by system: Linux uses bwrap or Landlock, macOS uses Seatbelt and Windows uses restricted tokens; the upper layer still sees the same tier semantics (source). Who uses them:
- Command-execution consumers: such as
dsh-bash-sandboxanddsh-pwsh-sandbox, which apply the current tier on their own execution path. - Remote backend:
dsh-sandbox-sshplaces execution in a remote environment, following the same tiers. - Provider package and semantics are separate: the concrete mechanism is implemented by a provider package, while the upper layer sees one
SandboxModevocabulary — so a DSH plugin does not need a separate logic per system. - Before installing a plugin that runs commands: assess which tier it needs; check its description under Settings → Plugin Market, which is DSH Plugin Hub, before deciding.
How to choose a tier: from tight to loose
Choose a tier from tight to loose, widening only by actual need rather than starting at the widest (source). A workable order of questions:
- Ask "does this task need to change files": if it only reads and analyses,
read-onlyis enough — do not open writes by default. - Then "does it only change the current project": if the output lands inside the workspace directory,
workspace-writeis the fit. - Only then "does it truly need the whole disk": consider
danger-full-accessonly when writing outside the project is genuinely required, and know the consequences. - Reassess after the change: when the task is done, tighten the tier back so the default state stays safe.
Notes on the sandbox
Read the sandbox as "a tiered limit on file-system effects" and you will not assume it governs the network.
- Three tiers from tight to loose:
read-only→workspace-write→danger-full-access. - Tighter by default is safer: if read-only suffices, do not move to writable; if workspace-write suffices, do not open full access.
- Scope is limited: it constrains file-system effects only; network and process visibility are separate.
- Crossing goes through approval: a request for wider permission is not silently allowed.
- Backends differ by system: Linux, macOS and Windows mechanisms differ, but the semantics are consistent.
- Escalate with care:
danger-full-accesscarries the most risk; tighten it back when done. - Plugin capability boundary in DSH plugin capabilities and permission boundary; escalation errors in fixing sandbox escalation errors.
Source: DeepSeek Harness docs - sandbox subsystem, docs - architecture overview.
FAQ
The three DeepSeek Harness sandbox modes are read-only, workspace-write and danger-full-access, and the mode decides how far an execution's writes are restricted. read-only forbids writes, workspace-write allows writes but confines them to the workspace directory, and danger-full-access applies no file-system restriction at that layer.
The DeepSeek Harness sandbox only governs file-system effects; network access and process visibility are outside its scope. It constrains which files an execution touches, which is the main target of isolation, so do not treat installing a sandbox as protecting every dimension.
DeepSeek Harness local sandbox backends differ by system: Linux uses bwrap or Landlock, macOS uses Seatbelt and Windows uses restricted tokens, while the upper layer still sees the same SandboxMode semantics. Consumers such as dsh-bash-sandbox and dsh-pwsh-sandbox apply the current mode on their execution path, and dsh-sandbox-ssh runs remotely under the same tiers.
A call that requests a wider tier than the current mode triggers approval handling rather than being silently allowed in DeepSeek Harness. The requested intent is validated against the allowed range before execution, and an escalation only makes sense when it moves toward wider access.
Choose the DeepSeek Harness sandbox mode from tightest to loosest, widening only by actual need instead of starting at the widest tier. Ask whether the task must change files at all, then whether it only changes the current project, and only then whether it truly needs full-disk access.
Related Terms
- SandboxMode
- SandboxMode is DeepSeek Harness's file-system effect tier: read-only, workspace-write or danger-full-access, deciding how far an execution's writes are restricted.— DeepSeek Harness docs - sandbox subsystem
- read-only
- read-only is the tightest DeepSeek Harness sandbox mode: execution may read but not write, suited to retrieval, analysis and report generation.— DeepSeek Harness docs - sandbox subsystem
- workspace-write
- workspace-write is the middle DeepSeek Harness sandbox mode: writes are allowed but confined to the workspace directory, the everyday default for tasks that must produce files.— DeepSeek Harness docs - sandbox subsystem
- danger-full-access
- danger-full-access is the widest DeepSeek Harness sandbox mode: no file-system restriction applies at that layer, so execution may write anywhere and should be used with care.— DeepSeek Harness docs - sandbox subsystem
Sources
- DeepSeek Harness docs - sandbox subsystem· deepseek-harness
- DeepSeek Harness docs - architecture overview· deepseek-harness