Introduction¶

The core idea of DeepSeek Harness (DSH) is “everything is a plugin.” When developing or integrating third-party plugins, a direct question arises: how to grant a plugin the necessary execution capabilities without compromising the security of the host environment. If a plugin runs directly in the DSH process, it gains all permissions of the host, which creates a security risk.

The dsh-capsule plugin addresses this issue by creating a separate Bubblewrap process on Linux systems. It runs compatible third-party DSH clients inside an isolated environment, with the host enforcing integrity verification and permission control.

Plugin Overview¶

Plugin name: dsh-capsule

Core positioning: Provides an OS-level isolation capsule for third-party DeepSeek Harness plugins.

Maintainer: 2-c-q

Category: admin-security

License: MIT

This plugin creates new user, PID, mount, and network namespaces using Bubblewrap, physically isolating plugin code from the host environment and preventing malicious or faulty code from damaging the host system.

Core Features¶

Based on the plugin’s functional description, its core capabilities include:

Execution isolation: Runs compatible third-party DSH clients in a fresh Linux Bubblewrap process. No client-side code is loaded into the DSH process, and no code remains in memory between invocations.
Integrity verification: The trusted host verifies an integrity-pinned JavaScript artifact, ensuring that unaltered code is executed.
Isolated contribution: Discovers and contributes information inside isolated describe units.
Tool registration: Registers real DSH tools and static system prompt sections on behalf of the host.
Per-invocation execution: Each tool invocation starts a new isolated unit, ensuring state isolation.

Installation and Activation¶

Before installing, make sure the host system meets the prerequisites.

Prerequisites:

Bubblewrap: The host must have Bubblewrap installed and must support the --ro-bind-fd option.
System restrictions: Ubuntu 24.04 may require loading an AppArmor profile to allow unprivileged user namespaces.

Installation command:

Install the plugin package through the DSH plugin manager:

dsh plugin --profile <profile> add github:2-c-q/dsh-capsule

Dependency requirements:

The installer accepts the following peer dependencies, with version range 0.1.0-rc.5 to 0.2.0:

@deepseek-ai/dsh-subprocess
@deepseek-ai/dsh-system-prompt
@deepseek-ai/dsh-tools

Typical Usage¶

After installation, a capsule instance must be defined in the configuration file.

1. Prepare the host environment

Install Bubblewrap on Debian or Ubuntu:

sudo apt-get update && sudo apt-get install --yes bubblewrap

If using Ubuntu 24.04, it is recommended to install the AppArmor profile shipped with the system to ensure user namespace functionality is available.

2. Configure the capsule

In the configuration file (usually via cordis.patch.yml), define the capsule root directory, manifest file, and policy. Using echo-capsule as an example:

- id: dsh-capsule-host
  config:
    capsules:
      - root: /absolute/path/to/dsh-capsule/examples/echo-capsule
        manifest: capsule.json
        policy:
          capsuleId: example.echo
          tools:
            - capsule_echo
          promptSections:
            - capsule.echo.guidance
          grants: []
    bubblewrapCommand: bwrap
    # ... 其他配置参数（如 maxManifestBytes, maxFrameBytes 等）

3. Workspace access

To grant a plugin permission to read files from the host filesystem, use workspaceRoot and policy.

Request: Declare {"kind":"workspace-read","path":"reference/context.txt"} in the plugin manifest.
Configuration: Specify workspaceRoot in the capsule configuration and match the path in the policy grants.

After configuration, the file is mounted read-only inside the capsule at /workspace/reference/context.txt. Note that v0.1 only supports exact read-only mounts for existing regular files; directory mounts and write mounts are not supported.

Use Cases and Considerations¶

Use cases:

Running untrusted or not-yet-verified third-party DSH plugins in the host environment.
Strictly isolating a plugin’s access to host system resources (files, network, processes).

Important notes:

Linux limitation: The v0.1 isolation provider only supports Linux systems.
Security boundary: The isolation boundary is a proof of the execution world between the host and the capsule. If the host environment (such as the Bubblewrap version) or configuration (such as manifest/policy) does not match, the capsule cannot be activated.
Threat model: The goal of this plugin is to limit runtime permissions. It does not protect the host from kernel vulnerabilities, Bubblewrap vulnerabilities, side-channel attacks, or denial-of-service attacks.
Permission model: The v0.1 protocol supports only workspace-read. It does not support workspace-write, network-connect, subprocess-exec, or storage. Directory mounts are also not treated as a capability in the current version.

Summary¶

dsh-capsule provides a lightweight Bubblewrap-based sandboxing solution for the DeepSeek Harness plugin ecosystem. By running plugins inside an isolated Linux process and verifying their integrity, it effectively limits plugin runtime permissions and reduces the risk of damaging the host environment. For developers who need to integrate external plugins, this is a necessary isolation mechanism.

Plugin directory: https://www.skillhub.cn/plugins/2-c-q/dsh-capsule

GitHub repository: https://github.com/2-c-q/dsh-capsule

dsh-capsule: Provides Linux Sandbox Isolation for Third-Party DeepSeek Harness Plugins