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:

1. 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.
2. 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.
3. 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.
4. 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:

1. read-only: no writes allowed, execution can only read. Suited to "look but do not change", such as retrieval, analysis and report generation.
2. 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.
3. danger-full-access: no file-system restriction at this layer, the strongest and most careful tier. The danger in 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:

1. 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-only and workspace-write tiers.
2. Network access is not its job: whether a command can reach the network, and where, is outside this sandbox and needs separate assessment.
3. Process visibility is not its job either: which other processes on the machine a command can see is likewise out of scope.
4. 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:

1. Validated before execution: the execution carries the tier intent it requires, and the system checks it against the currently allowed range.
2. Crossing triggers approval: a request for wider permission is not silently allowed but goes down the approval path for a human to decide.
3. 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:

1. Command-execution consumers: such as dsh-bash-sandbox and dsh-pwsh-sandbox, which apply the current tier on their own execution path.
2. Remote backend: dsh-sandbox-ssh places execution in a remote environment, following the same tiers.
3. Provider package and semantics are separate: the concrete mechanism is implemented by a provider package, while the upper layer sees one SandboxMode vocabulary — so a DSH plugin does not need a separate logic per system.
4. 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:

1. Ask "does this task need to change files": if it only reads and analyses, read-only is enough — do not open writes by default.
2. Then "does it only change the current project": if the output lands inside the workspace directory, workspace-write is the fit.
3. Only then "does it truly need the whole disk": consider danger-full-access only when writing outside the project is genuinely required, and know the consequences.
4. 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.

1. Three tiers from tight to loose: read-only → workspace-write → danger-full-access.
2. Tighter by default is safer: if read-only suffices, do not move to writable; if workspace-write suffices, do not open full access.
3. Scope is limited: it constrains file-system effects only; network and process visibility are separate.
4. Crossing goes through approval: a request for wider permission is not silently allowed.
5. Backends differ by system: Linux, macOS and Windows mechanisms differ, but the semantics are consistent.
6. Escalate with care: danger-full-access carries the most risk; tighten it back when done.
7. 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.