DeepSeek Harness Plugin

Install @busabase/dsh-plugin 0.1.5 or newer to connect DeepSeek Harness to Busabase Cloud or to Busabase on your computer.

Before You Start

• Install Node.js >=24.18.0
• Make sure pnpm is available
• Install DeepSeek Harness

You do not need to start Busabase before installing the plugin. Startup order matters only after you select Existing server mode.

1. Install or Update the Plugin

For a new installation, run:

npx @deepseek-ai/dsh plugin --profile web add @busabase/dsh-plugin

This installs the current DeepSeek Harness CLI and Busabase plugin releases. The published package already includes the required Skills and has no install lifecycle script, so no build approval is required.

If the plugin is already installed, update it instead:

npx @deepseek-ai/dsh plugin --profile web update @busabase/dsh-plugin

Adding or updating a Bundle does not change a running profile. Restart DeepSeek Harness after either command.

2. Choose a Server Mode

Managed Local: let the plugin manage Busabase

Choose Managed Local when you want an account-free setup and on-device data. No configuration is required: the plugin defaults to http://localhost:15419 and starts Busabase when needed, or reuses a healthy server already on that address.

Existing server: connect without managing the process

Choose Existing server when Busabase Desktop or another application already embeds or runs Busabase. Start that server on a loopback address, then create or edit $DSH_HOME/profiles/web/cordis.patch.yml (~/.dsh/profiles/web/cordis.patch.yml by default) and add:

- id: busabase
  config:
    baseUrl: http://127.0.0.1:15419
    serverName: busabase
    server:
      mode: external

Replace the port if your server uses another one. server.mode: external tells the plugin to probe this address but never start or stop its process. Keep baseUrl on localhost, 127.0.0.1, or ::1; a non-loopback address selects remote OAuth mode instead.

Cloud: hosted and shared workspaces

Choose Cloud when you already have a Busabase account, collaborate in a team workspace, or use more than one device. Create or edit $DSH_HOME/profiles/web/cordis.patch.yml (~/.dsh/profiles/web/cordis.patch.yml when DSH_HOME is not set) and add this list item:

- id: busabase
  config:
    baseUrl: https://busabase.com
    serverName: busabase

If the file already contains other entries, append this item instead of replacing the file. A profile override replaces the matched plugin's complete config, so keep any other non-default Busabase settings you need in the same block.

Do not put a password or token in this file. On first Cloud startup, the plugin opens busabase.com in your browser for OAuth. DeepSeek Harness stores the resulting grant in its credential store and reuses it on later starts.

3. Start DeepSeek Harness

Start or restart the Web profile:

npx @deepseek-ai/dsh --profile web

If the browser does not open automatically, visit http://127.0.0.1:3080.

What happens next depends on the selected connection:

• Managed Local: Busabase stays stopped until the first busabase_start call or Inspector use.
• Existing server: start Busabase first. busabase_start verifies the server and reconnects MCP tools, but never starts it. If the server is unavailable, the call reports that address instead of launching a replacement.
• Cloud: your default browser opens for Busabase sign-in and consent. After approval, the Cloud MCP tools are registered automatically; there is no busabase_start tool in Cloud mode.

4. Verify the Selected Connection

First confirm the installed Bundle and effective configuration:

npx @deepseek-ai/dsh plugin --profile web list --depth=0
npx @deepseek-ai/dsh --profile web --dump-config

The first command should include @busabase/dsh-plugin. In the busabase row, --dump-config should show the selected baseUrl; Existing server mode must also show mode: external under server.

For either local mode, try:

Call busabase_start, then list my Busabase Bases and summarize what each one contains.

For Cloud, complete browser authorization and try:

Call auth_verify, then list the top level of my Busabase workspace.

In every mode, the Agent can read approved data and submit proposed writes as ChangeRequests. Both local modes support review and previews inside the Inspector. In Cloud mode, follow the canonical Busabase links to review and merge in Busabase Cloud.

Switch Modes Later

Change the busabase item in the profile patch and restart DeepSeek Harness. To return to Managed Local, remove the override or use:

- id: busabase
  config:
    baseUrl: http://localhost:15419
    serverName: busabase

Existing Cloud credentials stay in the DSH credential store; they are not copied into the Local workspace.

If Installation Fails

If the install command says a build script was not approved, you have an older release that declared a preinstall script. Update to the current release, then run add again; the current package does not need build approval:

npx @deepseek-ai/dsh plugin --profile web update @busabase/dsh-plugin
npx @deepseek-ai/dsh plugin --profile web add @busabase/dsh-plugin

Restart DeepSeek Harness afterward. If only busabase_start appears, call it first; the other Busabase tools appear after connection.

If Cloud sign-in does not open, check the terminal for the authorization URL. The first OAuth callback must reach the same computer that runs DeepSeek Harness; remote or headless setups may require loopback port forwarding.

If Existing server mode reports that Busabase is unavailable, verify the configured host and port, start the owning application, and call busabase_start again. The plugin intentionally does not fall back to a managed process in external mode.

Update or Remove

npx @deepseek-ai/dsh plugin --profile web update @busabase/dsh-plugin
npx @deepseek-ai/dsh plugin --profile web remove @busabase/dsh-plugin

Restart the Web profile after updating or removing the Bundle. Use --dump-config whenever the UI still appears to use the previous connection.

Busabase DeepSeek Harness plugin source