01 · Setup
Get started
This chapter takes you from an empty DeepSeek Harness (DSH) profile to a running bridge. You install the bundle, create the isolated Python environment, save a connection and load the daemon setup in an idle CIW (the Virtuoso Command Interpreter Window). Do this once per profile. Later conversations reuse the managed runtime.
Requirements
The plugin installs into one DSH profile. It reaches Virtuoso over SSH (Secure Shell) and runs SKILL (Cadence's scripting language) inside that CIW. Check these requirements once per profile, not per conversation. No Cadence or Spectre license or simulation hardware is included.
| Requirement | Why it is needed |
|---|---|
| DeepSeek Harness 0.2.2-class with Cordis 4.x | The Host half, the client panels and the tool registrations target that API surface. The plugin is verified against DSH 0.2.2-rc.1 / Cordis 4.1. |
| Node.js | The Host half runs on the Node.js runtime that DSH already provides. Nothing is installed separately. |
| Python 3.9+ | Creates the isolated venv that holds virtuoso-bridge-lite. The executable is configurable as source.pythonPath / settings.pythonPath. |
| Package index access | The first install downloads the bridge source and its dependencies with pip. Later starts reuse the venv. |
git on PATH |
Needed for the git-checkout and git-repository source modes. An npm install needs neither git nor the submodule. |
OpenSSH ssh on PATH optional |
Recommended. Without it, installation stops and asks you to confirm before it continues with the bundled Paramiko backend only. |
| Reachable SSH host and a running Virtuoso CIW | Required for actual SKILL work: the runtime talks to a daemon inside that CIW. |
OpenSSH is the default backend. Paramiko exists for hosts without ssh, and the install continues with it only after you confirm. Test uses the same backend as the runtime, so changing the backend is a connection decision, not a per-call one.
Install the bundle
The plugin is a DSH bundle package, published as the public scoped package @nekomona/dsh-virtuoso-bridge.
From npm recommended
Ask the agent to install that bundle, or run the plugin manager's install_bundle with the package name:
Install the DSH bundle @nekomona/dsh-virtuoso-bridge.
The tarball carries the packaged subset of virtuoso-bridge-lite/ that the plugin installs — pyproject.toml, README.md, AGENTS.md, LICENSE, mcp_server.py, src/**, skills/** — plus virtuoso-bridge-lite.pin.json. The plugin therefore only creates its venv and pip-installs that source. No submodule and no Python checkout is required.
From a git checkout
Use a checkout when developing the plugin itself. Clone with the submodule, initialise it if the clone was made without --recurse-submodules, then install the local bundle through DSH:
git clone --recurse-submodules https://github.com/nekomona/dsh-virtuoso-bridge.git <plugin-directory>
git submodule update --init virtuoso-bridge-lite
Install the plugin bundle at <plugin-directory>, for example by asking the agent. Reload the DSH page once so the browser bundle is current. A page loaded before installation can still recover through the loopback panel-token bootstrap, but only a reload picks up the newest client bundle.
Data directory
Runtimes, settings, the venv and plugin logs live under the profile's data directory. The cache directory in Runtime defaults holds pip wheels, git checkouts, script jobs and large results.
%USERPROFILE%\.dsh\virtuoso-bridge\<profile>\
settings.json
venv\
instructions\ installed upstream skills, README.md and AGENTS.md
tunnels\ Host-owned tunnel records
<profile> defaults to default. Override it with $DSH_PROFILE when the Host process exports it, with config.dataDir, or with VB_PLUGIN_DATA_DIR.
Bundled source installs the pinned virtuoso-bridge-lite/ git submodule at an exact commit (1f186abfbb3d658211743cd707f3156ed2f59a87, recorded with its date and license in virtuoso-bridge-lite.pin.json). .gitmodules declares no branch, so upstream main moving cannot change the installed source. Never run git submodule update --remote. It is the only command that follows a moving branch.
Create the environment
Open the dsh-virtuoso-bridge entry in the left sidebar's global panel list (the waveform mark, beside Plugins and Automation tasks). The full-page configuration panel opens on Server connections. Environment, defaults, storage and activity stay folded until you need them.
- Use Install when the venv is missing. Use Diagnose once it exists.
- The
⋯menu holds Repair and Update. - Source and install log (collapsed) holds the source mode, Python executable, repo path or git URL/ref, pin JSON, install log and backend details.
Install creates a private venv and sets it up:
- installs the tool and its dependencies;
- installs the SSH extra (
paramiko+PySocks) by default; - verifies
import virtuoso_bridgewithruntime/vb_probe.py.
You can also run virtuoso_bridge_setup action install or update. Pass confirm: true for the Paramiko-only case. Action preflight reports the supported backends and the extra definition.
The Python executable is configurable as source.pythonPath / settings.pythonPath. Source selection and pythonPath are saved together. Install and update first persist the visible source draft, so the chosen source is actually used.
If ssh is not on PATH, installation stops and asks you to confirm before it continues with the Paramiko backend only. The same confirmation is required for virtuoso_bridge_setup action install. Nothing silently falls back.
Helpers start from the plugin venv with -E -s. They inherit no PYTHONPATH/PYTHONHOME/VIRTUAL_ENV and no ambient VB_* values. The probe refuses to report ready when the imported virtuoso_bridge comes from outside the plugin venv, except an explicitly configured editable local checkout. The plugin never copies the user's ~/.virtuoso-bridge/.env.
Choose a source mode
Three modes live on the same environment card. The mode and pythonPath are saved together. Update reuses the selected mode.
| Mode | Source | Refresh behavior |
|---|---|---|
| Bundled source default | The pinned virtuoso-bridge-lite/ git submodule from this plugin; no network access to the tool repository. |
Uses the pinned commit. A missing or uninitialised submodule fails with an actionable error naming git submodule update --init virtuoso-bridge-lite (and the pinned commit). npm users never hit that state. |
| Local development repo | Editable install from source.localRepoPath. |
Code edits are picked up on the next runtime start. Reinstall with Repair when packaging metadata changes. |
| Git repository | Clones source.repoUrl at source.gitRef into the profile data directory, then installs it. |
Update fetches the ref again. |
In every mode, pip needs the normal package index on the first install. Only the tool-repository access differs.
Save a connection and start it
A connection is the address and the permission the runtime starts from. Fixed-port and automatic-session daemons find the endpoint in different ways. Connections and credentials covers that choice.
- On Server connections, add a row, or let the agent call
virtuoso_bridge_runtimeactionsave_connection. Creating a row or changing its SSH target asks for approval unless the session has Full access. - Press Start, or call action
start. A fixed-port start probes the configured daemon port first. If a signed daemon answers, the runtime attaches to it and skips deployment. - Read the runtime state, not a single log line.
- When the state is
waiting, run the printedload("...")line in the intended idle CIW. The health poll then moves the runtime torunning, and a responsive daemon clears the load hint.
The runtime reports starting, connecting, waiting and running. In waiting, the network side worked and the CIW still has to load the printed setup. In running, the daemon answered. Runtime lists every state, including needs-trust and error.
load("/path/to/virtuoso_setup.il")
Use the path the deployment printed. Copy that line rather than retyping a path. The Host health loop checks status every 20 seconds, and it inspects X11 dialogs while the daemon does not answer.
Deployment prepares and uploads the bootstrap and prints the load("...") line. Loading it is a human action in an idle CIW. A reconnect or a plain restart does not deploy files or reload the setup. The runtime stays in waiting until you load the setup.
Verify the first run
virtuoso_bridge_runtime action status returns a compact projection. It covers setup readiness, connection endpoints, runtime state, daemon and instance state, attached agents and running actions. Verbose install logs, source and venv debug paths, tunnel internals and full tracebacks stay in the UI. The UI keeps the full state.
| Field | Read it when |
|---|---|
setup.installed, setup.venvReady | Confirming environment readiness. A false value means install or diagnose first, before blaming the host. |
state, connectionStatus | Reading the runtime phase and the connection verdict: ready, no-response, auth-failed, unreachable or unknown. |
daemon, daemonProbe | Seeing what answers the configured port: probe states ready, no-listener, legacy, auth, timeout. |
setupHint | Finding the load("...") line. It is present only before first readiness and disappears once a daemon responds. |
instance | Automatic sessions: the selected port, Virtuoso pid, work_dir and user. |
attach | Fixed mode: attached, port and setupPath when a signed daemon was attached and deployment was skipped. |
health, dialog, errorSummary | Responsiveness, a blocking dialog title, and the stage, message and hint of a failure. |
agents, activeActions | Which sessions are attached and which operations are still running. |
Then prove the daemon answers with the smallest possible call:
virtuoso_bridge_api({
action: "call",
target: "client",
method: "execute_skill",
args: ["1+1"],
description: "Check the daemon answers"
})
running means execute_skill("1+1") answered through the daemon. If the call returns a value but the CIW printed warnings, read the CIW block attached to the result before you decide the call did nothing.
Test reports on four layers: SSH, the remote Python, the scratch root and the daemon port. It runs even when the runtime is stopped. Start owns the tunnel and sidecar. Connections and credentials covers the connection checks.
The complete state is in the right sidebar's dsh-virtuoso-bridge tab. It shows connection state, daemon and health summary, remote project working directory, dialog warnings and agent activity. The composer dot is green when connected, yellow when waiting or blocked, and red on error. It breathes green while an operation for that session runs, and it is absent when the session has no active runtime.
status with waitMs waits for an in-flight start to settle, or until the budget expires. The next step after a start is usually this waiting status, not a sleep.
Next steps
Continue with Connections and credentials for fields and host-key trust, and Agent tools for the tool surface. Runtime covers states and architecture.
Canonical source for this chapter: docs/plugin-guide.md sections 3–7; the root README.md is only an introduction.