Introduction

DSH plugin installation is profile-oriented. For scenarios requiring SessionPersistence to be stored in S3 or an S3-compatible endpoint, dsh-session-s3 provides an installable DSH plugin. It adopts wal3-Lite: immutable JSONL fragments plus CAS manifest, coordinating writers via If-None-Match / If-Match instead of directly modifying existing fragments. Below is an introduction to its positioning, installation, configuration, and verification methods.

What is this

dsh-session-s3 is a community DSH plugin maintained by gengmao under the MIT license. It provides an S3-backed SessionPersistence provider for DeepSeek Harness, registered as ctx.sessionPersistence, and replaces the profile’s sessions row via a Cordis bundle patch.

Core Features

  • Provides S3-backed SessionPersistence provider for DeepSeek Harness.
  • Uses wal3-Lite design: immutable JSONL fragments + CAS manifest, relying on If-None-Match / If-Match.
  • Each fragment has SHA-256; Phase 1 does not use setsum.
  • Coordinates concurrent writers via a single compare-and-swap object without modifying fragments.
  • Registered as ctx.sessionPersistence, replacing the profile sessions row via Cordis bundle patch.
  • Supports AWS SDK credential chain, and S3-compatible endpoints like R2, Tigris, MinIO, SeaweedFS, GCS interop, etc.
  • Provides a library helper createProvider(), including append, read, compact, close methods.

Installation and Enablement

Plugins are installed into profiles, not globally. The runtime environment requires Node >= 22.

Install from GitHub

First, run the following command to add the plugin to the web profile:

dsh plugin --profile web add github:gengmao/dsh-session-s3

If there is no global dsh, you can use npx:

npx -y @deepseek-ai/dsh plugin --profile web add github:gengmao/dsh-session-s3

In a pnpm >= 10 environment, git-hosted prepare scripts may be blocked. If the add command fails, allow dsh-session-s3 to build and then re-run the installation command.

Install from Local Checkout

If already in a local directory, you can use:

dsh plugin --profile web add ./dsh-session-s3

Restart and Remove

After adding, restart:

dsh web

Or use the profile:

dsh --profile web

Remove the plugin:

dsh plugin --profile web remove dsh-session-s3

npm Install (Unconfirmed Release)

Verified resources list dsh plugin --profile web add dsh-session-s3, but it is unconfirmed whether the npm package has been published. Use the GitHub installation method above as a priority.

Configuration

Set bucket and optional endpoint in the profile overlay. The path is:

$DSH_HOME/profiles/web/cordis.patch.yml

Key configuration items to pay attention to are as follows:

  • bucket: Required.
  • endpoint: Optional; if set, must be http or https.
  • accessKeyId / secretAccessKey: If set, both must be set simultaneously; they are static keys and do not include a session token.

Do not put access keys in the Cordis patch. Prefer using the AWS SDK default credential chain.

If the configuration is invalid, all issues will be listed during the loading phase.

Typical Usage and Verification

In the DSH seam, the plugin is registered as ctx.sessionPersistence, replacing the profile sessions row. The library helper createProvider() provides append, read, compact, close methods.

To check the CAS behavior of the target bucket, you can use:

aws s3api put-object --bucket my-sessions --key dsh/_probe --body /dev/null --if-none-match '*'

list() and listSnapshots() call ListObjectsV2, so they require s3:ListBucket permissions.

Suitable Scenarios and Notes

Suitable for the following scenarios:

  • DSH profile requires S3-backed SessionPersistence.
  • Using R2, Tigris, MinIO, SeaweedFS, or GCS interop.
  • Using AWS SDK credential chain.
  • Need immutable JSONL fragments and CAS coordination for writes.

Notes:

  • License is MIT. The plugin runs with the current dsh process permissions; source code and license should be checked before installing.
  • Requires Node >= 22.
  • Plugins are installed to profiles, not globally.
  • bucket is required.
  • endpoint, if set, must be http or https.
  • Do not save access keys in Cordis patch.
  • list() / listSnapshots() require s3:ListBucket.
  • Independent npm install uses legacy-peer-deps=true because @deepseek-ai/dsh-type-meta is not published on npmjs.
  • Whether the npm package has been published is unconfirmed.

Links

GitHub:

https://github.com/gengmao/dsh-session-s3

The directory page URL does not appear in the verified resources.