Skip to main content

Installation

Requirements​

  • DeepSeek Harness 0.2.x
  • Node.js 22 or later
  • a DSH profile with the web interface
  • at least one language-model route capable of running the game master and child agents

rclone is optional. Install it only if you want to sync the roleplay library between devices; ordinary local play does not call it.

A dedicated DSH profile is recommended. The bundle adds its own roleplay preset, sidebar experience, settings and session tabs. Keeping them in a dedicated profile avoids changing an unrelated DSH workspace.

Install the bundle into the profile in which roleplay should be available:

dsh plugin --profile <profile> add @dsh-agentic-roleplay/all

The bundle installs the roleplay core and @dsh-agentic-roleplay/state. Restart the profile after installation, then open Role Play in the DSH sidebar.

Microphone input is optional. Install and enable Voice Input from DSH's own plugin list if you want it. The roleplay bundle does not install DSH speech packages, so DSH can keep them on the same release as the runtime. You can use its SenseVoice provider, an API speech-to-text provider, or both.

Keep only the all bundle layer selected. The core and state packages also ship layers of their own for installing them without the bundle, and those layers add the same plugin rows. With both selected the profile holds two roleplay rows, and DSH refuses to save Settings → Role Play ("this deployment did not accept these values"). If you manage plugins with a plugin manager, deselect the @dsh-agentic-roleplay/core and @dsh-agentic-roleplay/state layers and keep the packages installed, then restart. The Role Play settings page shows a warning, and the log an error, when it finds this.

First-run checklist​

  1. Set the storage root under Settings → Role Play.
  2. Configure at least one language-model route. The project-maintained provider integration is described in AI services.
  3. Open Role Play → Worlds and add the sample world or create your own.
  4. Select the play button on a world card, choose a playable character, and start the session.

The bundle does not include model credentials or download models. Optional media and retrieval features appear only when their corresponding services are available.

Storage root​

Open Settings → Role Play and choose an absolute roleplay root. ~/dsh-roleplay is the default; a leading ~ is supported. Worlds, avatars, session databases and media live below this root. Ordinary plugin configuration remains in the DSH profile.

Changing the root switches the catalogue after the new value is valid. An invalid edit is rejected and the previous root remains active.

Treat this folder as your roleplay library. Backing it up preserves authored worlds, reusable avatars, session databases, generated media, and session settings. Do not point two simultaneously running profiles at the same root.

Updating​

Update the bundle and restart the profile. Before a DSH minor-version upgrade, check the project release notes: the child-agent implementation uses a small set of version-sensitive DSH composition APIs.

Moving from 0.9.0​

Version 0.9.0 included DSH's Voice Input components. Version 0.9.1 removes them from this bundle so they can follow DSH's release independently. With the profile stopped, install 0.9.1 over the existing package:

dsh plugin --profile <profile> add @dsh-agentic-roleplay/all@0.9.1

Start the profile again. If you use microphone input, open the plugin manager and enable DSH's Voice Input plugin. Do not grant a version exemption to old speech packages. Your roleplay root is separate from the installed packages, so this update does not remove worlds or sessions. Back up the profile configuration before the update if you have edited its patch files by hand.

Continue with AI services.