Chapter 8 — Plugins, Bundles, and Profiles: Giving DSH New Powers

4 min read · 934 words · 13 sections

What You Will Learn

• Distinguish Plugin, Bundle, and Profile;
• Understand how a plugin gets installed;
• Use Plugin Manager to install, enable, disable, and remove;
• Understand the trust boundary of third-party plugins;
• Troubleshoot "installed but not working."

8.1 Three Words, Three Layers

Plugin is capability. Bundle is the installer package. Profile is the environment.

Plugin

A Plugin is the runtime unit. It can:[1]

• Register tools;
• Register services;
• Register Skills;
• Add UI;
• Listen to events;
• Change Agent behavior.

Bundle

A Bundle is an npm package that usually contains:[2]

• A cordis.patch.yml, or a list of patch files;
• Plugin code;
• Possibly Skills, UI assets, or icons.

It packages "which plugins to add and how to configure them" so a user can install it in one step. Its rows remain patchable by higher layers.

One Bundle can mount many Plugins; one Plugin can be referenced by different Bundles.

Profile

A Profile is an installation environment:[3]

• desktop: the desktop app;
• web: the browser;
• headless: a one-shot command-line run.

It contains:

• Installed Bundle list;
• Its own cordis.patch.yml;
• Third-party plugin dependencies.

The Profile decides what this environment installs; the Bundle decides what the installation contains; the Plugin decides what actually runs.

8.2 How They Relate to Presets

Profile (desktop)
 ├─ Bundle A (dsh-base)
 ├─ Bundle B (dsh-web-app)
 │    └─ declares Presets: standard / creator / ...
 └─ Bundle C (your plugin)
      └─ mounts Plugin: your tools

Preset (standard / creator)
 └─ selects a set of Plugins for one Agent

• A Bundle can declare Presets;
• A Preset chooses which Plugins an Agent gets;
• A Profile chooses which Bundles the environment installs;
• A Plugin is the capability that runs.

8.3 Installing with Plugin Manager

In Desktop, open the Plugin Manager (or Plugins page).

Typical flow:

1. Open the plugin page;
2. Search or select a Bundle;
3. Read the description, permissions, and dependencies;
4. Confirm install;
5. Restart or reload if prompted;
6. Check whether tools, Skills, or UI appeared.

Before installing

• Is the source trustworthy?
• What permissions does it request?
• Does it depend on an external CLI or service?
• Does it run install scripts?
• Does it conflict with an existing plugin?
• Can it be uninstalled?

After installing

• Is it enabled?
• Are the new tools present?
• Are the new Skills visible?
• Are there errors or warnings?
• Does it require a restart?

8.4 Why "Installed but Not Working"

Troubleshooting order

1. Check Plugin Manager status and errors;
2. Check whether a restart is needed;
3. Check dependencies and versions;
4. Check for conflicts;
5. Check whether the tool is scoped to a Preset;
6. Check logs and diagnostics.

8.5 Configuring a Plugin

Many plugins expose settings:

• Binary path;
• API URL;
• Timeout;
• Output limit.

DSH plugins usually declare these with a Config schema; Plugin Manager renders a form.

Rules:

• Prefer the UI;
• Do not hand-edit the profile's package.json;
• Do not hand-edit cordis.patch.yml unless you understand layer order;
• Reload/restart after changes;
• Store secrets safely.

8.6 The Trust Boundary

This is the most important section.

A plugin is not just configuration. It may execute code.

Installing a third-party plugin means letting someone else's code run inside your DSH process. It may:

• Read files;
• Access the network;
• Execute commands;
• Modify configuration;
• Install dependencies;
• Run install scripts.

Therefore:

• Install only trusted sources;
• Review permissions and code;
• Do not grant unnecessary full access;
• Test in a scratch workspace first;
• Make sure you can uninstall or roll back;
• Do not give secrets to an untrusted plugin.

8.7 Uninstall and Rollback

Before installing, know how to remove it:

• Can Plugin Manager disable/remove it?
• Does it leave configuration or data?
• Does it change the profile's bundle list?
• Does it require a restart?
• Can you roll back the version?

Back up the profile, or at least record the state before installation.

Try It

1. Open Plugin Manager and inspect the installed Bundles;
2. Find the difference between enabled and disabled;
3. Do not install anything yet; read one plugin's permissions;
4. Pick a plugin you use and see which tools/Skills it registers;
5. Write down how you would disable it if it broke.

Common Pitfalls

• Confusing Plugin and Bundle: capability vs. installer package.
• Assuming a Bundle is enabled after install: check selection, reload, and dependencies.
• Hand-editing profile config: easy to break layer order.
• Ignoring permissions: plugins can execute code.
• Not restarting: many plugins need a reload.

Summary

• Plugin = capability, Bundle = installer package, Profile = environment.
• A Preset chooses which Plugins an Agent uses.
• Install/enable/remove through Plugin Manager; do not hand-edit the profile.
• Third-party plugins are code, not pure configuration.
• If it does not work, check status, reload, dependencies, conflicts, and Preset scope.

Part III Exercises

1. Explain Plugin, Bundle, and Profile to a friend in one sentence each.
2. Open Plugin Manager and count the enabled Bundles.
3. Read one plugin's permissions and dependencies; decide whether you would install it.
4. Explain why a Preset is not a security sandbox.
5. Write a rollback checklist for a broken plugin.

References

1. DeepSeek Harness plugin development
2. npm publish documentation
3. DeepSeek Harness GitHub repository

All links are public sources; product behavior may change between versions.