Profile, Bundle, and Plugin explained

These three terms answer different questions: which composition to run, which configuration to distribute, and which capability code to execute.

Profile

A profile lives at $DSH_HOME/profiles/<name> and represents a named runnable composition. It stores a bundle list, external plugin dependencies, and its own cordis.patch.yml.

Bundle

A bundle distributes a set of Cordis configuration entries through an npm package. Its package.json declares the patch file in dsh.bundle.patch.

Plugin

A plugin is a module that registers services, events, tools, or other capabilities on the Cordis ctx. One bundle may load several plugins, and one profile may combine several bundles.

Configuration layering order

Later layers win:

1. Bundles from the profile manifest, in list order.
2. The profile’s cordis.patch.yml.
3. Home-level $DSH_HOME/cordis.patch.yml.
4. Command-line --patch arguments, in argument order.

dsh --profile web --dump-default-config
dsh --profile web --dump-config
dsh --profile web --patch ./extra.cordis.yml --dump-config

Critical warning: this is not a deep merge

A patch replaces the target entry’s entire config. If the original configuration also contains a port, runtime expression, or other fields, replacing just one key can remove all of them.

Replacing a config containing !!js with a literal object may also prevent application arguments such as --port from taking effect. Always run --dump-config after a change and inspect the final result.

Install and remove external plugins

dsh plugin --profile my-profile add <package-or-git-spec>
dsh plugin --profile my-profile remove <package>

pnpm 10+ blocks prepare for Git source dependencies by default. Adding allowBuilds permits installation-time code to run outside the agent sandbox. Allow only trusted sources and pin a specific commit.