Introduction

In a DSH environment, a profile typically contains not just profile configuration but also items such as settings.yaml, .agent-presets, and vendor/ link directories. When switching machines, manually copying directories can easily result in missed link mappings, vendor packages, and settings configurations. Conversely, direct importing lacks version verification, backups, and failure rollback capabilities.

The following introduces dsh-migrate. It organizes DSH configuration migration into a standardized process: exporting and packing on the source machine, importing and restoring on the target machine, with pre-checks, backups, and verification in between, and a rollback mechanism upon failure.

What is this

dsh-migrate is a DSH configuration migration tool, positioned as:

DSH configuration migration tool: Export/Pack → Machine Switch Restore → Verify + Rollback.

It is maintained by ygcdsj, with the GitHub repository at ygcdsj/dsh-home-migrate, package name dsh-migrate, and license MIT. package.json indicates the version is 0.0.11, and the README is marked as experimental.

It primarily addresses DSH configuration migration within the same OS environment, covering profile configuration, settings.yaml, .agent-presets, and vendor/ link directories. The MVP is limited to the same OS; cross-OS migrations will be explicitly rejected during the pre-check phase.

Core Features

Export

The export phase scans ~/.dsh, with the scope including:

  • Profile configurations
  • settings.yaml
  • .agent-presets
  • vendor/ link directories

Field-level credential scanning and masking are performed on settings and presets, with details processed into the manifest’s secretReport.

Suspected credentials within vendor package configuration files are masked in place. If the migrated vendor package depends on masked values (e.g., an API token), it must be reconfigured on the target machine.

Pack

The export artifact is a single .dshmig file, essentially a ZIP archive.

It contains a built-in manifest, including:

  • Version
  • Platform
  • File manifest
  • sha256 checksum
  • link mappings

Import

The import phase performs a pre-check before executing the restoration. The pre-check verifies:

  • Same OS
  • DSH version
  • Disk space

Import does not directly overwrite existing profiles; instead, it defaults to creating a new profile with a name like:

<name>-migrated

If a profile with the same name already exists on the target machine, it will be automatically incremented.

The restoration order is:

  1. Recalculate link: paths
  2. Restore vendor, presets, and settings
  3. Run pnpm install
  4. Verification chain
  5. Automatic rollback on failure

The verification chain includes link resolution and dsh --dump-config.

Entry Points

dsh-migrate provides two types of entry points:

  • The “Migration” entry in the Settings page, which includes export and import wizards
  • Host tools dsh_migrate_export and dsh_migrate_import, which can be called directly by the agent

Installation and Enabling

Verified installation examples are as follows, for the web profile:

# Run inside the profile directory
dsh plugin --profile web add dsh-migrate

The package information is displayed as follows:

version: 0.0.11
license: MIT
peerDependencies:
  @deepseek-ai/dsh-client-ui-slots: ^0.1.1-rc.2
  cordis: >=4.0.0-rc <5

Starting from version 0.0.9, the migration package includes dsh-migrate itself. Historical versions (≤0.0.8) do not include it, and the target machine requires manual installation.

Typical Usage

Export from Settings Page

On the source machine, execute:

  1. Go to Settings → Migration
  2. Preview the export content, including the file manifest, size, exclusions, and suspected credentials
  3. Execute the export

The export artifact is located at:

~/dsh-migrate-exports/*.dshmig

Import on Target Machine

On the target machine, execute:

  1. Go to Settings → Migration
  2. Enter the .dshmig path
  3. View the pre-check results and confirm item by item
  4. Confirm the checklist of steps
  5. Execute the import
  6. View the verification chain results and backup directory

After the import is complete, the migration results are located in the newly created <name>-migrated profile.

Start the Migrated Profile

If migrating the web profile, the verified startup example is:

dsh --profile web-migrated

Host Tools

Export preview:

dsh_migrate_export { dryRun: true }

Execute packing:

dsh_migrate_export { dryRun: false, outDir }

Import pre-check:

dsh_migrate_import { archive, dryRun: true }

Execute import:

dsh_migrate_import { archive }

It automatically rolls back if the import fails.

Development and Testing

Verified local test commands:

npm test

npm run test:install

Applicable Scenarios and Notes

dsh-migrate is suitable for migrating profile configurations between DSH environments on the same OS, especially in scenarios that require pre-checks, backups, verification, and rollback.

Please note the following when using it:

  • The README is marked as experimental.
  • The MVP is limited to the same OS; cross-OS migrations will be explicitly rejected during the pre-check phase.
  • Importing executes code within the archive, including pnpm install installation scripts and bundle plugin resolution. Starting the profile afterward will also execute the plugins within. Only import from trusted sources.
  • Credential exclusion and masking are best-effort, not an absolute guarantee. The export report lists unscannedFiles; please verify before transmission.
  • Credentials in vendor package configuration files are masked in place. If the migrated vendor package depends on masked values, it must be reconfigured on the target machine.
  • Overwriting is rejected if settings.yaml is a symbolic link.
  • The HTTP API is restricted to local loopback, with a Host whitelist, CSRF token, Origin same-origin policy, and Sec-Fetch-Site validation. Exposing DSH web to a local network increases import risk, as any accessible party could potentially import the archive.
  • git: dependencies are not packaged; they are re-fetched on the target machine during pnpm install, requiring network and credentials.
  • dsh-migrate runs under the permissions of the current DSH process; check the source code and MIT license before installing.

Conclusion

The value of dsh-migrate lies not in simple directory copying, but in organizing DSH configuration migration into a process that is previewable, verifiable, and rollbackable. For scenarios requiring same-OS machine switching and DSH profile restoration, it provides a relatively conservative approach.

Directory Page: Search for dsh-migrate in the DSH Community Directory; the Community Directory is an independent site with no official affiliation to DeepSeek / Hyperscience.

GitHub: https://github.com/ygcdsj/dsh-home-migrate