DeepSeek Harness on disk: DSH plugin and session data

Understanding DeepSeek Harness on disk starts with separating two trees: the program install directory and the data directory. The first is reinstallable (executables and dependencies); the second is yours (profile configuration, installed DSH plugin records, sessions, credentials). Plugin records live in the data directory, not with the program — which is why reinstalling keeps your plugins, and why launching with a different data directory makes them vanish. Once that is clear, backup, cleanup, migration and multi-machine alignment all get simpler: back up the data directory, clean the caches, reinstall the program.

Two trees: install directory versus data directory in DeepSeek Harness

Bottom line: the program directory can be deleted and reinstalled; the data directory cannot be deleted. Their separation explains almost everything else.

1. Check the data directory: echo $DSH_HOME. Empty means the default is in use, in which case you should set it explicitly so you always know where data lives.
2. Check the program location: which -a dsh and npm ls -g @deepseek-ai/dsh, confirming where it is installed and how many copies exist.

Option A: fix DSH_HOME explicitly (recommended)

Bottom line: an explicit data directory is the foundation for backup, migration and multi-entry sharing. The cost is one line of configuration.

1. Set and persist it:

export DSH_HOME="$HOME/.dsh"      # add to ~/.bashrc or ~/.zshrc
mkdir -p "$DSH_HOME"

2. Make every entry read the same value. The CLI inherits the shell environment; the desktop app and web UI need the variable in their launch environment too, or they will use a different directory.
3. Verify:

ls -la "$DSH_HOME"       # expected: profile and session subdirectories (names vary by version)

4. Payoff: once the location is fixed, backup scripts, migration and container volume mounts can reference it directly.

Option B: isolate environments by profile

Bottom line: when you need a work setup and an experiment setup, isolate with profiles rather than swapping data directories back and forth.

1. Use --profile to select separate profiles (confirm the flag with dsh --help), each with its own configuration and DSH plugin set.
2. Point experiments at a separate data directory for complete isolation — the same tactic recommended for diagnosing plugin conflicts (see DSH plugin conflicts).
3. Write one line of documentation per environment: which directory, which plugins. Future you will not remember.
4. Clean per profile, never the whole directory.

Option C: move the DeepSeek Harness data directory elsewhere

Bottom line: to relieve local disk pressure or share storage, move the data directory out. Three steps: back up, move, repoint — then verify.

1. Back up before moving so you can retreat:

cp -a "$DSH_HOME" "${DSH_HOME}.bak"
mv "$DSH_HOME" /Volumes/external/dsh-data     # adjust to your disk
export DSH_HOME=/Volumes/external/dsh-data

2. Repoint and make it effective for every entry, including desktop and web launch environments.
3. Verify three things: sessions open, the plugin list is complete, the service starts.
4. External drive caveats: network volumes and external disks can differ in permissions and filesystem behavior (case sensitivity, locking). Run a full pass before deleting the old copy.
5. Only then remove the old directory.

Three backup priorities for DeepSeek Harness data

Bottom line: even inside the data directory, priorities differ — back up credentials and configuration, archive sessions, skip caches.

1. Frequency: credentials and configuration after changes; sessions on a cadence matching your usage.
2. Method: copy the directory preserving permissions, or package subdirectories separately.
3. Verify restores: restore once into another machine or a temporary directory. An untested backup is not a backup.

Cleaning and reclaiming DeepSeek Harness disk space

Bottom line: touch caches and old sessions, never configuration or credentials. Look at size distribution first.

1. Option one: clear package caches (safest, fastest payoff):

npm cache verify        # verify first
npm cache clean --force # then clear if needed (slows the next install)

2. Option two: prune old sessions through session deletion operations rather than deleting the directory.
3. Option three: rebuild indexes and projection caches, which usually reclaims a lot — but only after confirming those directories are caches, not business data.
4. Measure before deciding:

du -sh "$DSH_HOME"/* 2>/dev/null | sort -h | tail -5
# expected: the largest subdirectories, which tells you what to clean

5. Never delete the whole directory as a cleanup strategy — that takes configuration and credentials with it.

DSH plugin troubleshooting around data locations

Bottom line: always check DSH_HOME, then version, then the plugin itself.

1. Plugins missing — check whether DSH_HOME changed (new shell, new container, new entry point).
2. Plugins missing after moving machines — reinstall from the manifest; packages do not move with the data directory.
3. Low disk — follow the priority table: caches, then old sessions, then consider moving the data directory.
4. Odd behavior after migrating — check external drive permissions and filesystem differences.
5. Multiple environments — use profiles, not directory swapping.
6. Repair status, stated honestly: the division of responsibilities here follows the official CLI's home and profile notes plus common practice. Subdirectory names and structure change between versions, so verify with ls "$DSH_HOME" and the official README.

Sources: apps/cli/README.md, apps/desktop/README.zh.md, npm Docs · npm cache.