The DeepSeek Harness (DSH) attachment mechanism currently uses local storage by default. When a session contains images, those images are saved directly to the disk of the machine running DSH. The dsh-attachment-s3 plugin provides an S3 storage backend for this mechanism, allowing session images to be persistently stored in cloud object storage.
Implementation Principle¶
The plugin implements the AttachmentStore interface in the DSH attachment mechanism and uses the same abstraction layer as the built-in @deepseek-ai/dsh-attachment-local backend. Because the DSH attachment mechanism can only configure one provider at a time, this plugin replaces the local backend through configuration replacement (not stacking), moving the attachment lifecycle from the host machine to an S3 bucket.
Core Features¶
- S3 storage backend: Stores attachment objects using S3-compatible services.
- Content addressing: Uses SHA-256 hashes as unique object identifiers to ensure data uniqueness and integrity.
- Write-once, verified reads: Uploads use conditional writes (
If-None-Match: *), and reads re-verify hashes and headers to prevent data corruption or tampering. - S3 service compatibility: Supports standard AWS S3 and other S3-compatible services (such as MinIO, Ceph, etc.).
Installation¶
Install it through DSH’s plugin command. After installation, the plugin disables the built-in attachment-local entry and adds an attachment-s3 entry through a patch file (cordis.patch.yml).
dsh plugin --profile <name> add @guaguasong/dsh-attachment-s3
After installation is complete, environment variables must be configured to enable the S3 backend.
Configuration and Usage¶
The plugin reads environment variables at startup. The following variables are required or directly related to configuration:
| Environment variable | Config field | Description |
|---|---|---|
DSH_ATTACHMENT_S3_BUCKET |
bucket |
Required. The object bucket used to store attachments. The process fails to start if it is not set. |
DSH_ATTACHMENT_S3_REGION |
region |
The region of the bucket. |
DSH_ATTACHMENT_S3_ENDPOINT |
endpoint |
The endpoint of the S3-compatible service (AWS S3 by default). |
DSH_ATTACHMENT_S3_FORCE_PATH_STYLE |
forcePathStyle |
Whether to force path-style access. |
DSH_ATTACHMENT_S3_PREFIX |
prefix |
The key prefix for stored objects. Defaults to attachments/v1. |
DSH_ATTACHMENT_S3_ACCESS_KEY_ID_REF |
accessKeyIdRef |
The environment variable name that holds the Access Key (a reference, not the value). |
DSH_ATTACHMENT_S3_SECRET_ACCESS_KEY_REF |
secretAccessKeyRef |
The environment variable name that holds the Secret Key. |
DSH_ATTACHMENT_S3_SESSION_TOKEN_REF |
sessionTokenRef |
The environment variable name that holds the session token. |
Verify Configuration¶
After installation and setting the environment variables, you can verify that the plugin is active by running the following command. This confirms that attachment-local was removed and attachment-s3 was added:
dsh --profile <name> --dump-config | grep -A2 id: attachment
Configure Credentials¶
Credential configuration follows the DSH credential mechanism: configuration items store environment variable names, not actual secret values. The plugin reads credentials from environment variables using these names at runtime. This design allows keys to be rotated without restarting the process. Both the Access Key and Secret Key references must be declared together, or neither should be declared, to avoid silent signing errors.
Attribute Limits¶
To maintain consistency with local backend behavior, the plugin inherits and implements the following image attribute limits:
maxImageBytes: Maximum encoded bytes per image (default 5 MiB).maxImagesPerMessage: Maximum number of images per message (default 20).maxMessageImageBytes: Maximum total encoded bytes per message (default 100 MiB).maxImagePixels: Maximum total pixels per image (default 40,000,000).maxImageDimension: Maximum dimension for one side of an image (default 2000).
Bucket-level S3 object policies (such as encryption, storage class, and lifecycle rules) are managed by the bucket itself. The plugin does not override these policies.
System Requirements¶
The plugin depends on the Node.js runtime. Before installing, ensure the environment meets the following version requirements:
Node.js ^22.19 || >=24
Uninstall¶
To restore local attachment storage, remove the plugin by running the following command:
dsh plugin --profile <name> remove @guaguasong/dsh-attachment-s3
Summary¶
dsh-attachment-s3 provides a standardized S3 attachment storage solution for DSH. It ensures data safety through content addressing and write-once, verified-read mechanisms. It is suitable for scenarios where session records and attachments need to be retained in the cloud long-term, or where session context needs to be shared across different machines by mounting the same S3 bucket.