Introduction

In the default sandbox of DSH, writing outside the workspace is usually restricted. If you want CLI commands or write/edit file tools within the sandbox to write to trusted directories outside the workspace, the common practice is to disable the sandbox or process approvals one by one. This, however, weakens the sandbox boundary and slows down the process.

The approach of dsh-sandbox-allowlist is to add a set of configurable “sandbox allowed directories” on top of the DSH default sandbox. These directories can be written to by CLI commands and write/edit file tools within the sandbox without needing approval each time, nor requiring the sandbox to be disabled.

DSH’s philosophy is “everything is a plugin”. The community directory is an independent site with no official affiliation to DeepSeek or Huanfang. dsh-sandbox-allowlist is maintained by developerdh and is licensed under MIT.

What is this

dsh-sandbox-allowlist is a DSH sandbox extension plugin. It appends configurable trusted directories to the write boundary of the DSH default sandbox, making these directories writable within the sandbox.

It solves the core problems of:

  • Trusted directories outside the workspace needing to be written to by CLI commands within the sandbox.
  • The write/edit file tool needing to write to trusted directories outside the workspace.
  • A desire to reduce per-operation approvals without directly disabling the sandbox.

Core Features

Sandbox Allowed Directories

The plugin manages allowed directories via the sandbox-allowlist namespace. The configurable directory list supports:

  • Multiple directories.
  • Wildcard **, matching a subtree.
  • Wildcard *, matching a single-level subdirectory.
  • Wildcard ?, matching a single non-separator character.

These directories are appended to the writable boundary of the DSH default sandbox. Writes that hit an allowed directory do not require approval each time, nor do they require disabling the sandbox.

CLI Commands and write/edit Tools

CLI commands within the sandbox can write to sandbox allowed directories outside the workspace.

The write/edit file tool can also write to sandbox allowed directories in workspace-write mode.

Note: Hitting an allow rule only skips the approval prompt; the command is still subject to file sandbox constraints, and the write disk boundary does not change.

Command Whitelist

The plugin supports command allow rules. Rule actions include:

  • allow: Allow without asking.
  • ask: Ask.
  • deny: Block.

Rules are evaluated in declaration order, and the last matching rule takes effect. When a command rule is not matched, the plugin delegates to the downstream, preserving the original deployment behavior.

Platform Coverage

The plugin covers:

  • Windows: ACL sandbox.
  • Linux: bwrap.

On Linux, landlock / seatbelt are currently not supported.

Configuration and Activation

Command rules and allowed directories can be edited via the settings page or settings.yaml. Changes take effect in real time without requiring a restart.

Pure Plugin Implementation

The plugin works via the plugin mechanism and does not modify any node_modules or official package code.

Windows Authorization Revocation

On Windows, deleting allowed directories from the configuration triggers an automatic reconciliation and revokes previously granted write ACEs.

If revocation fails, the relevant directories remain in:

$DSH_HOME/sandbox-allowlist-grants.json

and are automatically retried on the next reconciliation.

If directories still have ACEs after the plugin is uninstalled, you can use the emergency cleanup script:

node scripts/revoke.mjs

Installation and Activation

Node requirements:

>=20.11

Installation command:

dsh plugin --profile web add dsh-sandbox-allowlist

If performing local development and debugging, you can also pack the tarball first and then install the local package:

pnpm pack --pack-destination /tmp/pkg
dsh plugin --profile web add /tmp/pkg/dsh-sandbox-allowlist-*.tgz

After installation, you can edit the sandbox-allowlist configuration in the settings page or settings.yaml. The configuration takes effect in real time without a restart.

Typical Usage

Configuring Sandbox Allowed Directories

Allowed directories are configured under sandbox-allowlist.allowedDirs. Example:

sandbox-allowlist:
  allowedDirs:
    - 'D:\Shared\Tools'
    - 'D:\Shared\**'
    - 'D:\Data\logs\*'
    - 'D:\Work\202?'
    - '/opt/tools/**'

The meanings are as follows:

  • D:\Shared\Tools: Specifies a specific directory.
  • D:\Shared\**: Matches the subtree of that directory.
  • D:\Data\logs\*: Matches a single-level subdirectory.
  • D:\Work\202?: ? matches a single non-separator character.
  • /opt/tools/**: POSIX-style paths are also supported.

Patterns that anchor the drive letter or root directory with ** are rejected to prevent full disk traversal. Non-existent paths are skipped with a warning; if strict: true is configured, it will throw an error instead.

Configuring Command Whitelist

Command whitelist is configured under the same sandbox-allowlist namespace. Example:

sandbox-allowlist:
  commands:
    default: delegate
    rules:
      - tool: bash
        pattern: 'git *'
        action: allow

      - pattern: 'rm -rf *'
        action: deny

Explanation:

  • default: delegate means delegating to the downstream when no rule is matched, preserving the original deployment behavior.
  • rules are evaluated in declaration order, and the last matching rule takes effect.
  • pattern supports wildcards and can be used to ignore command arguments.
  • Hitting allow only skips the approval prompt; the command is still subject to file sandbox constraints.
  • deny directly blocks the command.
  • Rules can be edited via the settings page or settings.yaml, and take effect in real time without a restart.

Running Self-Check Tests

The repository provides the following test entry points:

npm test
npm run test:command-gate
npm run test:patch
npm run test:dry-mount

These commands can be used to verify behaviors such as wildcard expansion, command rules, patch combinations, and dry mounting.

Use Cases and Notes

Suitable for the following scenarios:

  • Need to write to trusted directories outside the workspace from within the sandbox.
  • Want to reduce per-operation approvals for CLI commands while preserving the sandbox boundary.
  • Want to use a unified configuration to manage allowed directories and command rules.
  • Using DSH in a Windows ACL sandbox or Linux bwrap environment.

Notes to consider before use:

  • Sandbox allowed directories will be directly written to by AI agents within the sandbox without approval. Only add directories you fully trust.
  • Allowed directories must exist and be owned by the current user.
  • On Windows, allowed directories need to be writable (i.e., allow modifying the DACL).
  • The write/edit tool only allows writing to sandbox allowed directories in workspace-write mode.
  • On Linux, bwrap is fully supported; landlock / seatbelt are currently not supported.
  • When upgrading dsh, if the relevant base class signatures change, this plugin may require minor adjustments.
  • The plugin runs within the current dsh process. You should check the source code, dependencies, and license before installing.

Conclusion

The value of dsh-sandbox-allowlist lies in that it does not require disabling the DSH default sandbox nor requiring approval for every write. Instead, it explicitly configures the trusted boundaries through configurable allowed directories and command rules.

Directory page:

https://www.skillhub.cn/plugins/developerdh/dsh-sandbox-allowlist

GitHub:

https://github.com/developerdh/dsh-sandbox-allowlist