DSH bundled profiles: first run, directory and manifest

DeepSeek Harness does not place five ready-made profiles on disk at install time; it initializes them on first use from built-in templates. web, headless, sdk, sdk-minimal, and acp each get a directory under $DSH_HOME/profiles/<name> and each has its own bundle set and patch timing. That difference explains why a web patch hot-reloads while a headless patch waits for a restart.

DeepSeek Harness: The five bundled profiles

Same launcher, different combinations and patch timing. Compare:(source)

web is for browser interaction, headless for one-shot tasks, sdk and sdk-minimal for JSON-RPC clients, and acp for automation clients. Only web explicitly applies patches live; the other four settle configuration at startup.

dsh web is a hard-coded alias for dsh --profile web. The other four have no alias; use dsh --profile headless or dsh --profile sdk-minimal.

DeepSeek Harness: What the directory and manifest contain

A profile is a manifest plus configuration layers, not one YAML file. After initialization, inspect three places:(source)

1. package.json — contains the dsh.profile manifest and ordered dsh.profile.bundles. Expected: the bundle list explains what the profile is made of.
2. cordis.patch.yml — the profile’s persistent patch. Expected: your edits live here and survive restarts.
3. node_modules/ — out-of-tree bundles and plugin dependencies. Expected: only present after installing third-party packages.

Bundled bundles (@deepseek-ai/dsh-base, dsh-web-app, dsh-headless, dsh-sdk-app, dsh-sdk-minimal, dsh-acp-app) always resolve from the current dsh installation, not from the profile’s node_modules. Upgrading dsh changes their version; out-of-tree bundles must be updated separately.

DeepSeek Harness: What first startup does

Startup does not read one complete config file; it starts from an empty root and stacks layers. The order:(source)

1. Create a missing profile — the five bundled names initialize from templates; other missing names fail. Expected: the directory and base manifest appear.
2. Apply bundle patches — in dsh.profile.bundles order. Expected: the base tree forms.
3. Apply the profile patch — profiles/<name>/cordis.patch.yml. Expected: profile-specific changes apply.
4. Apply the home patch — $DSH_HOME/cordis.patch.yml. Expected: shared preferences apply.
5. Apply command-line --patch — in argv order. Expected: temporary overrides win last.

Later layers win for the same row. A patch replaces the target row’s entire config, not deep-merge it; that is the root of many “I changed one field and lost the others” reports.

DeepSeek Harness: Three ways to enter a profile

Alias, explicit profile, and template replacement solve different problems. Compare:(source)

1. dsh web — alias for --profile web, for daily Web UI use. Expected: no need to remember the profile name.
2. dsh --profile <name> — any profile, including headless, sdk, and acp. Expected: launcher flags first, application arguments after.
3. --from-default-profile — replaces a custom profile with a template. Expected: good for rebuilds, not for upgrades that preserve configuration.

If you are starting for the first time, use dsh web. For CI, decide between headless and sdk first; their output contracts differ.

DeepSeek Harness: Common misconceptions

Most profile initialization problems come from assuming one profile behaves like another. Four:(source)

1. “All profiles hot-reload” — only web applies patches live; the other four apply at startup. Expected: restart after editing headless config.
2. “Any name auto-creates” — only the five bundled names do; other names need dsh plugin. Expected: no empty profile starts by accident.
3. “Bundled packages come from node_modules” — they resolve from the dsh installation. Expected: upgrading dsh changes their version.
4. “Patch is a deep merge” — it replaces the whole config. Expected: preserve the other fields in the row.

DeepSeek Harness: From template to a runnable check

After first initialization, verify four things instead of assuming “the directory exists”. Checklist:(source)

1. Directory and manifest — profiles/<name>/package.json exists and bundles are non-empty. Expected: not an empty directory.
2. Startup has no config error — no schema validation or module resolution failure. Expected: the process reaches a running state.
3. Patch applied — --dump-config shows the profile layer. Expected: not just a file edit without stacking.
4. Entry matches — web opens a page, headless runs a task, sdk answers a client. Expected: not “starts but unusable”.

If any fails, read the startup log and dump first; do not reinstall immediately.

Configuration layer order

A profile is built from an empty root, and the layer order decides who wins. Official order:

Later layers win; a patch replaces the whole config. This table explains “I edited the profile patch but the home patch overrode it”.

DeepSeek Harness FAQ

Which bundled profile is the lightest? sdk-minimal is the independent minimal combination, without dsh-base, keeping only the SDK protocol, adapter, local execution, and persistence. It is not a general Web UI.

Can I copy web configuration to headless? You can copy patches, but the bundles and tool sets differ. Dump the result and verify each field instead of assuming compatibility.

Can I rename a profile directory? Not recommended. Names appear in launch arguments, manifests, and credential references. Create a new name with --from-default-profile instead.

The short version: the difference between bundled profiles is not the name but the bundle set and patch timing. Read the manifest before editing configuration.