DeepSeek Harness Operator Guide

Plugin Model

Properties2
descriptionHow Bundles, profiles, Cordis patches, pnpm plugin management, and the loca trust policy fit together.
tagsdeek, reference, plugins

4 min read

Plugin Model

Trust boundary

Upstream external plugins execute trusted host code. MCP server commands also execute as trusted code outside the agent sandbox. Package installation is therefore code deployment, not a harmless user preference.

Upstream composition model

DeepSeek Harness uses Cordis plugin stacks:

  • A plugin package can declare a Bundle in package.json through dsh.bundle.patch.
  • That patch file contributes Cordis rows, typically with insert, insertBefore, insertAfter, replace, and remove operations.
  • A profile manifest declares an ordered dsh.profile.bundles list.
  • The launcher composes Bundle patches first, then the profile patch, the home patch, and optional CLI overlays.
  • Plugins run in the Host by default. Client plugins are an explicit remote boundary and must use serializable services rather than importing Host-only objects into browser code.

The Web alias selects the web profile under $DSH_HOME/profiles/web.

Profile filesystem

$DSH_HOME/
├── cordis.patch.yml
└── profiles/
    └── web/
        ├── package.json
        ├── cordis.patch.yml
        └── node_modules/
  • package.json owns plugin dependencies, the ordered Bundle list, and patchReload lifecycle.
  • cordis.patch.yml owns profile-local configuration.
  • The home cordis.patch.yml applies after the profile layer and affects profiles globally.
  • Out-of-tree packages resolve from the profile’s node_modules; shipped Bundles resolve from the dsh installation first.

For deek.service, $DSH_HOME is /var/lib/deek, so these files are sensitive service state.

Supported management command

Upstream exposes one plugin-management grammar:

pnpm dsh plugin --profile web <pnpm-verb> <package-or-git-spec>

The command initializes a missing profile, forwards the remaining arguments to pnpm in the profile directory, and reconciles the Bundle list against installed package metadata. Standard pnpm verbs such as add, remove, why, and update are forwarded.

After a successful add, remove, or update, restart the profile. A running process retains the Bundle membership loaded at startup. Ordinary valid edits to live-reload profile/home patches can apply transactionally without changing Bundle membership.

Git-hosted source plugins may need pnpm’s explicit build allowance before their prepare script can run. Treat any requested build allowance as an executable-code review gate, not a routine retry.

Loca deployment policy

The initial deek deployment enables no unreviewed external Bundle or MCP server.

For an approved plugin change:

  1. Identify the exact package name, source repository, revision, transitive dependencies, build scripts, Cordis patch, executable commands, network destinations, credential needs, and client code.
  2. Review the package as host code with the same privilege as deek.service.
  3. Install it only into a disposable profile/state root outside the live service.
  4. Build and exercise the resulting profile against non-sensitive workspace data.
  5. Record the intended Bundle ordering and composed configuration.
  6. Stop the service and back up /var/lib/deek.
  7. Promote the reviewed profile and any required immutable application material through the controlled release mechanism.
  8. Restart deek.service, authenticate with an existing valid cookie (or perform the private token exchange only when no valid cookie exists), and verify the plugin’s smallest intended behavior.
  9. Remove and roll back the complete Bundle if it needs broader filesystem, process, credential, or network access than approved.

Never let an agent install a package into its own running profile. Never use danger-full-access to work around a plugin’s incorrect path assumptions. Never place plugin credentials in package metadata, patches, the runtime copy, or the workspace.

Plugin configuration rules

Upstream patch examples use TypeScript-like !!js expressions evaluated by the config loader. That means a patch is executable configuration and deserves code review.

Use the source-derived configuration catalog for accepted plugin fields and defaults. Do not guess a key from an Agent Note, generated output from another revision, or a third-party example.

Preserve clean layering:

  • package defaults in the Bundle patch;
  • deployment-specific profile choices in the profile patch;
  • truly machine-wide choices in $DSH_HOME/cordis.patch.yml;
  • temporary diagnostic overlays only through explicit --patch, removed after use.

Graph View

Backlinks