Introduction

The design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” When developing agents or web applications, directly previewing pages from a local development server in DSH is a common requirement. Traditional preview methods often struggle to handle single-page application (SPA) route transitions, static asset loading, and backend API proxying. The dsh-preview-plugin plugin solves these problems by embedding a development server in an iframe and providing transparent SPA proxying.

What It Is

This is a live preview tab component for DSH, maintained by RaulLazaro. It allows any development server to be embedded in the preview tab of the DSH Web GUI, and supports SPA path proxying and multi-application monorepo scenarios.

Installation and Activation

To enable this plugin, modify the package.json of the DSH Web configuration.

  1. Add it as a dependency
    Add the following to the dependencies field in package.json:
    {
      "dependencies": {
        "dsh-preview-plugin": "file:~/workspace/dsh-preview-plugin"
      }
    }
  1. Add it to bundles
    Add dsh-preview-plugin to the dsh.profile.bundles array in package.json:
    {
      "dsh": {
        "profile": {
          "bundles": [
            "...",
            "dsh-preview-plugin"
          ]
        }
      }
    }
  1. Restart DSH
    Run the restart command to load the plugin:
    systemctl restart dsh

Typical Usage

Basic Preview

  1. Start the development server on the VPS (for example, npm run dev -- --host 0.0.0.0 --port 3000).
  2. Open the Preview tab in the DSH Web GUI.
  3. Enter the port number (such as 3000) in the URL field and click Go.
  4. The field automatically switches to the current page path (for example, /preview/3000/laptops?page=2#specs) and can be edited at any time; press Enter to navigate.

Multi-Application Monorepo

If the frontend and backend run on different ports (for example, frontend 4321 and Payload CMS backend 3001), you can configure multi-port proxying:
1. Start both servers.
2. Open the Preview tab.
3. Enter the frontend port (such as 4321) in the URL field and the backend port (such as 3001, multiple ports separated by commas) in the Backend field.
4. Click Go. At this point, API requests (such as http://localhost:3001/api/...) are automatically proxied into the iframe via /preview/3001/api/....

Agent Tool

An agent can use the set_preview_port tool to configure ports programmatically:

set_preview_port(port: 4321, backendPorts: [3001])

How It Works and Features

  • SPA proxying: The plugin registers the /preview/:port/* route. Static assets are proxied directly; for SPA navigation, the root HTML is returned and handled by client-side routing.
  • Intelligent routing: Fragment link (#section) navigation is supported, along with automatic rewriting for root-relative assets (such as /assets/photo.png) and srcset.
  • Real traffic: fetch, XMLHttpRequest, and form submissions are supported. Method, Body, Cookie, and Set-Cookie headers are preserved, enabling complete login and write operations.
  • Persistence: Preview configuration (frontend port + backend port) is stored in ${DSH_HOME:-~/.dsh}/preview-plugin.json and automatically restored after restart.
  • Security: The proxy targets only 127.0.0.1, and the iframe sandbox attributes are allow-scripts allow-same-origin allow-forms allow-popups.

Notes

  • Non-intercepted URL navigation: Native browser location.href, location.assign, and location.replace cannot be intercepted by scripts. The plugin detects these navigations and attempts to reload the path back under the proxy rules, but applications should use relative paths or import.meta.env.BASE_URL internally when constructing URLs.
  • Port restrictions: Port validation only allows 1 to 5 digits.
  • Permissions: The plugin runs with DSH process permissions. The source code and license (MIT) should be reviewed before installation.

Conclusion

This plugin provides convenient development preview capabilities for DSH. Related resources can be found on GitHub: https://github.com/RaulLazaro/dsh-preview-plugin