Foreword

DeepSeek Harness (DSH) users sometimes only want to change the background without directly modifying the frontend code when debugging locally or using dsh web daily. @starryhui/dsh-background is a custom DSH WebUI background plugin maintained by StarryHui, designed to integrate a local image folder into the DSH WebUI background settings.

It consolidates options such as image library scanning, cropping, transparency, blur, and slideshow into the “Settings → Background” section. Adjustments take effect immediately, and configurations persist after restart.

Plugin Overview

The license for @starryhui/dsh-background is MIT. It is intended for environments where DeepSeek Harness is installed and dsh web can start normally.

After installation, the plugin reads the local image folder and saves configurations in the background namespace of settings.yaml, ensuring they are retained after restart.

Core Features

Image Library Background

The plugin supports specifying a local folder and automatically scans images within it. Supported file types include:

png/jpg/webp/gif/bmp/avif/svg

Image selection supports thumbnail clicking and a “Random One” option.

Free Stretch and Crop Frame

On the preview image, you can drag the four corners or sides for free stretching, or pan within the frame. The background updates in real-time during adjustments.

Effect Adjustments

The following items can be adjusted:

  • Horizontal scaling
  • Vertical scaling
  • Position
  • Background opacity
  • Panel opacity
  • Gaussian blur

Display Modes

The plugin offers three display modes:

  • cover: Cropped to fill
  • contain: Fully displayed
  • fill: Stretched to fill

Multi-Image Crossfade Slideshow

If the image library contains multiple images, switching uses a dual-layer crossfade transition. You can also choose to switch sequentially based on the image library order.

Real-Time Effect

All adjustments refresh the background instantly. Configurations are persisted in the background namespace of settings.yaml and are retained after restart.

Installation and Enabling

npm Installation

First, install using the npm package. The following command installs @starryhui/dsh-background@latest into the web profile:

dsh plugin --profile web add @starryhui/dsh-background@latest

After installation, restart dsh web:

dsh web

Then open “Settings → Background” to configure the image library and effects.

Handling Installation on Older Versions

If installed on an older version, it may be related to pnpm 11+’s publish age gate. pnpm 11+’s default publish age gate minimumReleaseAge includes a 24-hour interval, which might silently isolate newly published versions.

You can set this in the profile’s pnpm-workspace.yaml:

minimumReleaseAge: 0

Or add @starryhui/* to minimumReleaseAgeExclude.

After configuration, run the update command:

dsh plugin --profile web update @starryhui/dsh-background@latest

Installation from GitHub Repository

Installing from the GitHub repository is mainly for development and debugging. First, clone the repository and enter the directory:

git clone https://github.com/StarryHui/dsh-custom-background.git
cd dsh-custom-background

Then install the current directory into the web profile and start it:

dsh plugin --profile web add link:$(pwd)
dsh web

Installation from the repository requires Node.js >= 22 and pnpm.

If you modify src/, you need to rebuild in the packages/client directory of the DSH source checkout:

tsc -b
tsdown --env.DSH_BUILD_FACE client

After building, copy the new lib/ back to this repository.

Configuration and Running Instructions

The plugin’s background configuration is read and written through self-built same-origin routes, including:

/dsh-bg/state
/dsh-bg/save
/dsh-bg/css

It does not rely on the namespace whitelist of the official settings RPC.

System requirements are as follows:

  • DeepSeek Harness is installed, and dsh web can start normally.
  • No additional requirements for npm installation.
  • Installation from the repository requires Node.js >= 22 and pnpm.

Use Cases and Notes

This plugin is suitable for users who have local images and want to customize the DSH WebUI background.

Before installation, it is recommended to review the source code and the MIT license. After the plugin loads, it runs with the current dsh process permissions, so please ensure the installation source is trustworthy.

Conclusion

The value of @starryhui/dsh-background lies in making DSH WebUI background adjustments a persistent local configuration: specifying an image library, dragging the crop frame, adjusting transparency and Gaussian blur, enabling crossfade slideshow, and writing configurations to the background namespace of settings.yaml.

GitHub repository: https://github.com/StarryHui/dsh-custom-background