How to create an isolated profile for DSH plugins

A DeepSeek Harness profile is an independent runtime configuration under $DSH_HOME/profiles/<name>, holding package.json (the dsh.profile manifest and ordered bundles) plus cordis.patch.yml; create one with dsh --profile <name> --from-default-profile <template> and install DSH plugins per profile. This guide covers what a profile is, how to create one and how plugins get in.

What a DeepSeek Harness profile is: directory layout and bundles order

A DeepSeek Harness profile directory holds package.json (recording out-of-tree plugin dependencies, the dsh.profile manifest and the ordered bundles) and cordis.patch.yml, with plugins installed into its node_modules, and profiles invisible to each other by default (source). Understand the layout in four steps:

1. Check the location — each profile lives at $DSH_HOME/profiles/<name>. Expected: <name> is what you pass to --profile or dsh <name> at startup.
2. Read package.json — beyond ordinary dependencies it carries the dsh.profile manifest and bundles. Expected: bundles is an ordered list deciding how bundle patches stack.
3. Know the common bundles — such as @deepseek-ai/dsh-base, dsh-web-app, dsh-headless, dsh-sdk-app, dsh-sdk-minimal and dsh-acp-app. Expected: different shapes use different bundles, with web and headless each taking their own.
4. Read cordis.patch.yml — this is the profile's user patch layer, overriding bundle defaults. Expected: it affects only this profile.

The stacking order is: each bundle's patch (in bundles order) → the profile cordis.patch.yml → the home-level $DSH_HOME/cordis.patch.yml → --patch. Later layers win.

How to create a custom DeepSeek Harness profile: --from-default-profile and templates

Create a profile from a default template with dsh --profile <name> --from-default-profile <template>, where the template decides the profile's shape; launch it with dsh <name> or dsh --profile <name> (source). Follow these steps:

1. Pick a template — by purpose: dsh-web-app for interactive web, dsh-headless for unattended tasks, dsh-sdk-app for building on top. Expected: the template directly sets the default bundle composition.
2. Create the profile — run dsh --profile <name> --from-default-profile <template>. Expected: package.json and a patch file appear under $DSH_HOME/profiles/<name>.
3. Choose a memorable name — do not use the reserved name desktop. Expected: an invalid name fails creation or collides with the desktop build.
4. Verify by launching — start with dsh <name> or dsh --profile <name>. Expected: you enter that profile's shape.
5. Inspect the defaults — use --dump-default-config when needed to see the profile's bundle defaults. Expected: you confirm what the template brought in.

How to install a plugin into a specific DeepSeek Harness profile: dsh plugin --profile

Use dsh plugin --profile <name> <pnpm args> to install a plugin into that profile's node_modules; profiles are invisible to each other by default, so a plugin installed into A has no effect in B (source). The order of operations:

1. Confirm the target profile — decide which profile the plugin should serve. Expected: a plugin meant for headless need not go into web.
2. Install per profile — run dsh plugin --profile <name> <pnpm args>. Expected: the dependency lands in that profile's package.json and node_modules.
3. Verify the install — launch the profile and check the plugin list. Expected: the plugin appears in this profile and not in others, confirming isolation.
4. Share config when needed — to reach every profile, configure it centrally in the home-level cordis.patch.yml. Expected: config is shared, but dependencies are still installed per profile.

To trial community plugins in a profile, find the plugin name in the DSH Plugin Hub and install it per profile.

Caveats and limits of DeepSeek Harness profile configuration

1. desktop is reserved: the desktop build owns it, the CLI refuses to boot or dump with it, so give custom profiles another name.
2. Isolation is the default: plugin installs, permissions and models all apply per profile and do not sync across profiles.
3. bundles order is meaningful: the order decides whose defaults win, so do not shuffle it casually.
4. The template sets the starting point: a wrong template brings unsuitable default bundles, and starting over beats patching config.
5. The profile directory is backup-ready: copy the whole $DSH_HOME/profiles/<name> to take that profile's plugins and config with you.

For install differences across profiles, see dsh plugin multi-profile install; for file locations, see Where DeepSeek Harness config files live.

Sources: dsh CLI README (official repository)