# Installation guide For the usual setup, start with the [Quick start](../README.md#quick-start). This guide covers prerequisites, custom installations, verification and maintenance. ## Requirements - An existing DSH Web installation using @deepseek-ai/dsh 0.1.2-rc.1. - Node 22.19 or newer in the Node 22 line, or Node 24 and newer. - npm and pnpm on PATH. npm runs this project's scripts; DSH's plugin manager requires pnpm. - At least one provider already configured in DSH. This plugin supplies no provider credentials and does not sign into accounts. - A terminal on the machine or inside the container where DSH actually runs, using the same operating-system account and DSH_HOME as the existing service. The qualified native libraries are Cordis 4.0.2, DSH storage-domain and typert-protocol 0.1.2-rc.1, and Zod 4.5.4. Setup checks these pins and refuses incompatible copies. Other DSH releases need compatibility validation. Linux is tested; macOS and Windows are not yet independently qualified. The responsive layout still needs browser/platform-specific acceptance. ## Get the source Download the source ZIP from the project's GitHub page or an approved release. Extract it into a permanent directory outside DSH's own installation. Open a terminal in the extracted directory containing package.json. The local-link installation depends on that directory remaining in place. Moving or deleting it breaks the link. Do not copy DSH settings, sessions, credentials or backups into the plugin directory. ## Check your launchers ```sh node --version npm --version pnpm --version dsh --version ``` If a launcher is missing, make the existing installation's executable directory available on your terminal's PATH. A running DSH service does not necessarily mean its launcher is on your interactive terminal's PATH. For the supported DSH release, a known runtime directory also lets you invoke its CLI directly: ```sh node "PATH_TO_DSH_PACKAGE_DIRECTORY/lib/bin.js" --version ``` Replace the placeholder with the directory containing the actual @deepseek-ai/dsh package.json. That Node/launcher prefix can replace dsh in subsequent commands. The native plugin manager still needs pnpm on PATH. Do not reinstall DSH or start another service merely to find its launcher. ## Connect native libraries Run these commands in order and stop if any command fails: ```sh npm run setup npm run check ``` Setup connects the package to the actual DSH installation's native libraries, without downloads or a second Cordis graph. Do not begin with npm install: separate native-library copies can create incompatible service registries. If automatic discovery cannot identify the correct installation, use an explicit override: ```sh npm run setup -- --runtime-dir "PATH_TO_DSH_PACKAGE_DIRECTORY" npm run check -- --runtime-dir "PATH_TO_DSH_PACKAGE_DIRECTORY" ``` A container needs its own runtime directory, not a path belonging to the host. Conflicting dependencies, ambiguous runtimes and unsupported versions are refusals to resolve—not reasons to force an overwrite or disable security checks. ## Register the Web profile In a Linux/macOS shell, while still in the plugin directory: ```sh dsh plugin --profile web add "link:$PWD" ``` In Windows PowerShell: ```powershell dsh plugin --profile web add "link:$((Get-Location).Path)" ``` Substitute your actual profile name if it is not web. Use the service's usual account and DSH_HOME; another account or profile will not change your existing GUI. This command registers the package and its bundle. Do not edit shipped agent presets or put this shared service into an individual agent preset. Normal DSH package-manager security checks remain in effect. ## Restart and verify Wait for active agent work to finish, restart the existing DSH instance through its normal terminal command, service manager or container, and refresh the same Web address. Do not start a replacement server. No new port, proxy, shell build or browser build is required. DSH may require its own browser authentication after restart; this plugin neither supplies nor changes it. Open a main conversation and look for Sub: beside the normal picker. The providers and models should match those configured in DSH. Inherited is the default. To verify routing, choose a model, create a new subagent, and check its recorded request route. A child created before the selection should keep its earlier model. Child views are read-only. Manual provider inference may incur normal provider charges; automated tests use deterministic substitutes and make no provider inference calls. Native continuable descriptors may retain their original model seed. Inspect the child's actual request route and binding rather than relying on a descriptor label alone. ## Updates and backups Back up the DSH profile, sessions and the subagent_model_policy storage domain before changes. The domain lives under the configured DSH home's storages directory; it holds policy and binding records, not source. See [Privacy](PRIVACY.md). Finish active delegations, retain a backup of the working source, replace it with a reviewed compatible version, rerun setup/check, and restart the existing instance. If the directory changes, register the new local link again. There is no automatic update mechanism. DSH upgrades normally leave separately stored source and policy records intact, but can break APIs. Check compatibility and run tests against the new runtime before relying on it. Recreate peer links if the runtime moves. Never erase saved bindings to hide a compatibility failure. This package has its own neutral service and storage identities. It does not automatically migrate records from a differently named plugin. Do not run two independent subagent-routing plugins together. Complete work under the old integration and plan migration separately. ## Removal Stop active delegations, then remove the package from its profile: ```sh dsh plugin --profile web remove dsh-subagent-model-policy ``` Restart the existing instance afterward. Removal stops model-binding enforcement: retained records alone cannot preserve routing while the plugin is absent. Keep records and backups if you may reinstall; unregistering the plugin is not a request to delete them. ## Troubleshooting | Symptom | Check | |---|---| | No Sub: control | Correct Web profile/account, package and bundle registration, source directory still present, existing service restarted, page refreshed. | | dsh or pnpm not found | Existing launcher directories on this terminal's PATH; see the direct Node-launcher alternative above. | | Native module cannot be found | Rerun setup against the runtime that owns the service; do not copy libraries from another machine. | | No providers or models | Configure them in DSH first; authentication and availability remain DSH's responsibility. | | Reasoning option rejected | Choose an option supported by the selected adapter. | | Existing child keeps its old model | Expected behavior. Create a new child to use a newly saved choice. | | Another tab changed the policy | Reopen the control and review the latest value; revision checks prevent silent overwrites. | | Old UI after editing source | DSH caches client assets. Restart the existing instance and refresh; editing a file alone is not live deployment. | ### Initial binding save failure A binding is the saved record of which model and reasoning effort a child must use. If that first record cannot be written, the plugin blocks requests for that child in the current DSH process. The failure marker is held only in memory. After restarting DSH, the missing binding means the child is treated as unmanaged and may use DSH's normal model choice instead of the requested Sub: selection. This is a known first-release limitation. It does not affect bindings that were successfully saved. To recover safely: 1. Resolve the reported storage error, such as insufficient disk space, incorrect permissions or a read-only filesystem. 2. Once storage is healthy, create a **new subagent** with the desired Sub: selection rather than retrying or resuming the failed-capture child. 3. Do not treat a DSH restart as recovery for that child. Preserve its session and diagnostic records if needed; do not erase policy data to hide the error. ## Running the tests After setup, run npm test. The archive regression additionally requires tar on PATH; normal installation does not. It packs and extracts the release into an isolated path with spaces and runs the tests there. The nested suite skips only that regression's own wrapper to prevent recursion. Review the summary: missing-tool or missing-runtime skips are not full qualification. All 61 tests pass on the qualified Linux setup. These tests do not prove arbitrary provider inference, interchangeable vision support, external-runtime routing or every platform's browser rendering. See [Contributing](../CONTRIBUTING.md) and [Architecture](ARCHITECTURE.md).