ChatGPTClaudeGrok / X / CursorGemini

Migrating an old dsh install: three things to align

Install & Get StartedPublished 2026-11-02Author: DeepSeek Plugin Market
dsh installmigrationDSH_HOMEpluginsrollback
Changing install method or machine means aligning three things: commands, plugins per profile, and data in DSH_HOME. Stop first and keep a rollback point.

Migration is not reinstalling; it is aligning three things: commands, plugins, and data. Do one and you get "the command works but history is gone" or "history is here but every plugin vanished".

dsh migration step one: stop and align commands

Stopping precedes every other step.

  1. Find the running dsh process and stop it normally; SIGINT or SIGTERM triggers disposal;
  2. Confirm the port is released with lsof -i :3080;
  3. Record the current version with dsh --version;
  4. Record the DSH_HOME path with echo $DSH_HOME, defaulting to ~/.dsh when empty;
  5. Back up the entire directory with a dated name.

Copying while it runs is the most common self-inflicted wound. A live profile writes configuration and plugin dependencies, so the copy can be half-written.

Back up the whole directory, not selected files. Sessions, logs, and credentials are inside; missing one shows up later as "something vanished".

Once the service is stopped and the backup exists, the first thing to align is the command entry.

Command alignment answers three questions: what the new entry is called, whether the old one remains, and which PATH wins.

  1. Install with the new method and confirm dsh --version;
  2. Run which -a dsh and check for multiple paths;
  3. If several exist, confirm the shell executes the new one;
  4. Search for aliases or scripts still hard-coding the old command;
  5. Update scripts, scheduled jobs, and shortcuts together.

An old entry does not always error; it may still run, just at an old version. That is the hardest case to notice, which is why step three cannot be skipped.

Do not run both during the transition. Two processes writing one DSH_HOME invite lock conflicts and version confusion.

dsh migration align two: plugins and profiles

Plugins follow profiles, not machines.

  1. Record the plugin list for each profile on the old setup;
  2. Confirm the new setup uses the same profile name;
  3. Reinstall by package name and version: dsh plugin --profile <name> add <package>;
  4. Restart and confirm the counts match;
  5. Check each entry, reading logs where needed.

"Half the plugins are missing" almost always means a profile name mismatch. Web, headless, and sdk are separate; a plugin in web never appears in headless.

Do not upgrade plugins during a migration. The goal is restoring the known-good state; upgrades are a separate change, so failures stay attributable.

dsh migration align three: data and DSH_HOME

Data alignment means pointing the new environment at the old data, not copying data into the install directory.

  1. Determine which directory the new environment uses as DSH_HOME;
  2. Restore the backup there, or point DSH_HOME at the backup location;
  3. Check permissions: only your user should read and write;
  4. Start once and confirm historical sessions are listed;
  5. Confirm credentials work by sending a message.

Never place DSH_HOME inside the install directory. Upgrades replace that directory, so data stored there is gambling on every update.

Credentials and settings are separate files. Restoring settings alone produces "the UI is fine but the model never answers", easily misread as a network problem.

dsh migration routes and acceptance

The route changes the emphasis.

npx to global: the version becomes controllable, so watch whether PATH hits the new command. CLI to desktop: the entry changes while data is shared, so prevent two processes from writing one DSH_HOME. Old machine to new machine: align Node version, native modules, and directory permissions before anything else.

Shared DSH_HOME between desktop and CLI needs care. The desktop app uses a reserved profile name that the CLI refuses to start or configure; concurrent use of one data directory invites interference.

Whatever the route, acceptance is not "it starts"; it is "three things are present".

  1. Sessions: history lists and opens;
  2. Plugins: count matches and entries work;
  3. Model: one message succeeds and errors are readable;
  4. Logs: new entries land in the new DSH_HOME;
  5. Version: dsh --version matches expectations.

Missing any one means only part was aligned. Identify which, revert that step, and avoid a full restart.

dsh migration rollback points and misalignments

One backup per step is cheap insurance.

  1. After stopping, back up DSH_HOME as <date>-pre-migrate;
  2. Before installing the new method, record the old command and version;
  3. Before editing PATH or aliases, copy the original configuration file;
  4. Verify after each change instead of testing everything at the end.

Roll back in this order: stop the new service, restore DSH_HOME, return to the old command. Data first, because a command rollback only changes the entry while a data rollback saves sessions and credentials.

Delete the backup only after the new setup has run for a while. Deleting early removes the only exit.

And post-migration symptoms almost always map to three places: command not found is PATH or a wrong install directory; no history means DSH_HOME points at an empty directory; fewer plugins means a different profile name; messages failing means credentials were not restored.

Fix the one that matches, and skip the full reinstall.

dsh migration next steps

All three aligned is the definition of done. To clean up leftover installs, read dsh disk usage and cleanup. To update plugins per profile, read updating plugins per profile. To pin versions, read pinning a version. To recover deleted sessions, read session recovery.

Sources: dsh CLI reference, dsh CLI README, DeepSeek Harness docs

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Will my sessions and plugins disappear when I switch from npx to a global install?

Switching dsh from npx to a global install deletes nothing automatically, but nothing aligns automatically either. Sessions, plugins, and settings live in DSH_HOME, default ~/.dsh, independent of the install method. The same DSH_HOME keeps the data; plugin visibility still depends on using the same profile name.

Why stop the running service before migrating?

A running profile holds write locks on configuration and plugin dependencies. Copying while it writes can produce half-written files that will not load. Stopping first also prevents two processes from writing the same directory.

Half the plugins are missing after migration. How do I restore them?

First check whether the new entry uses the same profile name as the old one, then whether the plugins were installed into a different profile. Profiles keep separate dependency trees; reinstall with dsh plugin --profile <name> add once confirmed.

What is the fastest rollback if the migration fails?

Stop the new service, restore the backed-up DSH_HOME, then return to the old command. Data rollback comes before command rollback: a wrong command only hides the entry, a wrong data directory loses sessions and credentials.

Related Terms

migration
Migration is the process of moving command entry, profile plugins, and DSH_HOME data to another install while keeping all three consistent in version and path.— dsh CLI reference
profile
A profile is a named assembly environment at $DSH_HOME/profiles/<name>, holding its own dependencies and patch files.— dsh CLI README
DSH_HOME
DSH_HOME is the data root for DeepSeek Harness, defaulting to ~/.dsh, holding profiles, settings, sessions, logs, and credentials.— dsh CLI reference
rollback point
A rollback point is a recoverable state saved before a migration step, usually a directory backup plus the recorded original command.— DeepSeek Harness docs

Sources