Installation and upgrades

August 30, 2026 · View on GitHub

Requirements

  • Node.js 24
  • DeepSeek Harness 0.1.1-rc.2 or later
  • A writable DSH Workspace

Install J4Agent into every Profile that should expose its UI or Agent tools. Keep the version pinned.

Install from a Git tag

dsh plugin --profile web add github:esonx/dsh-project-j4agent#v0.2.0-alpha.1
dsh --profile web --dump-config
dsh web

Install from a Release tarball

Download both dsh-project-j4agent-0.2.0-alpha.1.tgz and SHA256SUMS, verify the digest, then run:

dsh plugin --profile web add ./dsh-project-j4agent-0.2.0-alpha.1.tgz
dsh --profile web --dump-config
dsh web

Use a new test Profile first when changing DSH or J4Agent versions. Confirm that the plugin tree resolves, the Project Center dialog opens, and a Workspace can be initialized with a Work Item before upgrading a working Profile.

Upgrade

  1. Stop DSH processes using the target Profile.
  2. Back up each relevant Workspace's j4agent/ directory, including any j4agent.sqlite-wal and j4agent.sqlite-shm files.
  3. Install the new pinned tag or tarball with the plugin manager.
  4. For v0.1.x → v0.2.0-alpha.1, do not open the old database for writes. v0.2.0-alpha.1 uses a fresh Agent-native schema and intentionally returns J4_SCHEMA_RESET_REQUIRED for old stores; it does not migrate or delete them.
  5. Keep the backup, then initialize v0.2.0-alpha.1 in a new Workspace or explicitly move the old <workspace>/j4agent/ directory aside before initializing a fresh Project.
  6. Run --dump-config, start DSH and verify the newly initialized Project before development writes.

Do not replace or copy a live SQLite database while DSH is running.

Uninstall

dsh plugin --profile web remove dsh-project-j4agent

Uninstalling the plugin does not delete <workspace>/j4agent/. Remove that data manually only after DSH is stopped and a backup is no longer needed.