02 · Network
Connections and credentials
A connection is the address and the permission the bridge starts from. This chapter covers the saved fields, the two daemon modes, host-key trust, credentials, the deployment step and the scratch root that every upload lands in.
What a connection is
In DeepSeek Harness (DSH), a saved connection is not a form: it is a standing grant. Starting it opens an SSH (Secure Shell) session and a signed bridge daemon on that account. The agent can then run shell commands, Python and SKILL (Cadence's scripting language). Creating a row, or changing an existing row's SSH target, is therefore a modification outside the workspace.
virtuoso_bridge_runtimeasks for approval through DSH's permission card unless the session has Full access (danger-full-access).- A rejected or unavailable approval is final. Create the row from the configuration page instead of working around it.
- Saves that repeat the same SSH target (notes, scratch roots, sub-instances, environment) need no approval. The page's own Save button is user-initiated.
- Saving without an
idupdates the row with the same name, and the result saysupdatedorcreated. An existing row is retargeted whenhost,user,sshPort,jumpHost/jumpUseror a role host changes.
Two modes share every other field. A fixed-port connection points at a stable daemon endpoint and probes it. An automatic-session connection discovers registered daemons and uses an OS-assigned port. Which one you need depends on how the CIW (the Virtuoso Command Interpreter Window) is bootstrapped, not on the transport.
Fields
The configuration page keeps primary fields visible and folds advanced network settings, host roles, shell and Cadence environment, credentials, and workdir sub-instances. save_connection accepts the same names.
| Field | Default | Notes |
|---|---|---|
name | host, else connection | Display name and the key for a save without id. |
host | required | SSH target. A loopback host makes the row a local connection. |
user | — | SSH account; also the input for a derived fixed port. |
sshPort | 22 | SSH endpoint port, separate from the daemon port. |
port | derived from user | Fixed-mode daemon port; unused when autoSessions is true. |
autoSessions | false | Automatic discovery with an OS-assigned daemon port. |
instancePort | unset | Discovered port stored by select_instance; selects one instance before a restart. |
jumpHost, jumpUser | empty | Bastion host and optional account. A jump-host key is listed separately during trust. |
remoteWorkDir | empty | Absolute remote working directory; under automatic sessions it is also the discovery filter. |
daemonSetup | empty | A shared virtuoso_setup.il installed by virtuoso-bridge install-daemon; read-only to clients. |
sshBackend | openssh | openssh or paramiko. |
sshProxy | empty | Paramiko SOCKS5 proxy, socks5://host:port. |
identityFile | empty | Writes a per-connection SSH config that includes the user's own config. |
sshMaxSessions | unset | Advanced SSH setting; maps to the upstream SSH session limit. |
localPort | auto | Local port of the Host-owned tunnel; honoured when free. |
envShell | auto | auto, csh or sh. auto runs the Cadence script under both and keeps the shell that exposes virtuoso. |
cadenceEnvScript | empty | Cadence environment script sourced for remote work. |
remoteScratchRoot | global default | Absolute root preferred; ~/ is expanded and symlinks resolved before upload. |
clientId | empty | Optional client identifier recorded with the connection. |
daemonHost, deployHost, guiHost, spectreHost | empty | Role overrides for split-host topologies; see Split host roles. |
subInstances | none | Named absolute workdirs; see Workdir sub-instances. |
notes | empty | Free text stored with the row. |
A complete automatic-session row, as accepted by save_connection:
{
"name": "lab-virtuoso-auto",
"host": "virtuoso01.example.com",
"user": "designer",
"autoSessions": true,
"instancePort": null,
"remoteWorkDir": "/projects/example",
"daemonSetup": "/opt/virtuoso-bridge/v1/virtuoso_setup.il",
"sshPort": 22,
"jumpHost": "",
"sshBackend": "openssh",
"spectreHost": "",
"envShell": "auto",
"cadenceEnvScript": "/site/cadence/setup.csh",
"identityFile": "C:\\Users\\me\\.ssh\\id_ed25519"
}
Test reports on four layers: SSH, the remote Python, the scratch root and the daemon port. It runs while the runtime is stopped. Start owns the tunnel and sidecar.
Fixed port versus automatic sessions
Fixed port
Leaving port blank derives the bridge's stable per-user daemon port from the SSH user name (SHA-1, range 65000–65499), matching virtuoso_bridge.basic.bridge._default_remote_port. The CIW-side setup starts the daemon on that endpoint. A fixed legacy deployment is not discoverable after a CIW restart, so the deploy result carries recommendedAutoSessions and a guidance line.
Automatic sessions
With autoSessions, the daemon uses an OS-assigned port and port is unused. The plugin discovers registered daemons and selects one by port or workdir.
Discovery is read-only until you store a selection. A missing or ambiguous selection fails with the available list instead of silently picking one. select_instance stores the chosen port on the connection before a restart. Discovery runs before the tunnel opens, so the Host forwards to the instance the sidecar will select.
The decision is a deployment choice: a fixed port gives one stable endpoint for one CIW, while automatic sessions follow whatever instance is registered and selected.
Attach before deploy
A fixed-port start probes the configured port first. If this account's daemon answers with a signed capability handshake, the runtime attaches to it and skips deployment entirely. Status reports attach.attached and the reused setup path. Only when no attachable daemon is present does the runtime prepare the scratch root and deploy the setup.
A broken or missing scratch root therefore cannot block a live instance, including one deployed by another client or machine. Runtime covers the attach details.
Workdir sub-instances
A connection can carry a list of workdir sub-instances, each with a name and an absolute remote working directory. Each one starts with automatic sessions and an OS-assigned daemon port. It gets its own VBL (virtuoso-bridge-lite) profile and sidecar, and the plugin discovers it by workdir rather than by a fixed port.
- The runtime panel shows one card per sub-instance. The runtime id is
rt_<connection>__<sub-instance>. - Tool calls select one with
subInstance: "<id|name|/absolute/workdir>". - This allows several project CIWs under a single connection without assigning fixed ports.
Host keys and trust
On the first connection the plugin reads the offered host keys and stops in the needs-trust state with their SHA-256 fingerprints. The runtime is intentionally not started.
- The probe targets the endpoint SSH actually reaches. It resolves
HostName,PortandHostKeyAliasfrom~/.ssh/config, so a saved alias or non-default port does not report a fingerprint from a different server. - Each offered fingerprint is labelled with the host it belongs to. A jump host's key is marked separately.
- Nothing is trusted or added until the user confirms it: the runtime-panel button, or a
trust_hostcall made only after the user confirms the fingerprint. A trust call can only select a key the fresh probe offered. The argument never defines what is written. - Trust writes that single key to
~/.ssh/known_hostsunder both names a remapped host may be looked up by. OpenSSH uses the saved alias. Paramiko uses the resolved host name.
| Outcome | What it means | What to do |
|---|---|---|
| A key type is absent | A host normally offers several types (ed25519, ecdsa, rsa) and known_hosts usually contains only some of them. |
Untrusted, not changed. A host with at least one trusted type starts normally. SSH is pinned to the trusted types in the generated config. |
| A different key of the same type | The trusted key for that host has changed. | A conflict. It is never replaced automatically. Review it and remove the stale entry with ssh-keygen -R <host>, then start again. |
| First connection | Nothing is trusted yet. | needs-trust. Confirm the fingerprint, then start again. |
ssh-keygen -R virtuoso01.example.com
When a live agent session is available, the same confirmation appears as a question in the conversation. You do not need the right sidebar open. Failed starts report the stage, SSH and daemon output, the traceback and the host-key probe result in the runtime panel and the tool error.
Credentials and authentication
| Layer | Where it lives | Notes |
|---|---|---|
| Daemon token | DSH credentials service, as a grant record | Optional. Write-only in the UI and never returned by panels, tools or logs. Passed to the sidecar environment. |
| SSH authentication | The system SSH configuration (agent, keys, ~/.ssh/config) or Paramiko |
identityFile writes a per-connection SSH config that includes the user's own config. |
| Remote environment | cadenceEnvScript plus the cached shell detection |
envShell: "auto" tries csh and sh and keeps the shell that exposes virtuoso. The result is cached per connection and can be refreshed with detect_shell. |
| Local connections | The local bridge token file | localhost, 127.0.0.1 and ::1 skip SSH and use that file exactly like virtuoso-bridge local mode. |
A stored token is shown as stored and can be cleared. Its value is never read back, and the same rule holds for the panels, tools and logs.
Credential isolation is deliberate. The plugin never copies the user's ~/.virtuoso-bridge/.env. Every Python helper is isolated from it with the plugin's empty runtime env file before virtuoso_bridge is imported. Helpers start from the plugin venv with -E -s and inherit no PYTHONPATH/PYTHONHOME/VIRTUAL_ENV and no ambient VB_* values. The venv probe refuses to report ready when virtuoso_bridge comes from outside the plugin venv, except an explicitly configured editable local checkout.
Daemon deployment
Deploy daemon setup prepares and uploads the generated account bootstrap. It does not start a tunnel, start or connect a daemon, or load SKILL. After it succeeds, copy the returned line and load it in the intended idle CIW:
load("/path/to/virtuoso_setup.il")
Every connection row has the control. The same action is available as virtuoso_bridge_runtime action deploy_daemon, with replace: true as the explicit upgrade path for generated files. For a site-wide bootstrap, install the upstream shared bundle on the Linux Cadence host with virtuoso-bridge install-daemon <versioned-directory> and set daemonSetup to the printed virtuoso_setup.il. All automatic-session clients share that setup. Changing a client environment cannot retroactively update a running CIW.
| Result | Meaning |
|---|---|
| Returned load line | The exact line to load in the idle CIW. After an overwrite, load the newly returned line. |
recommendedAutoSessions | Set on a fixed legacy deployment, with a guidance line. That deployment is not discoverable after a CIW restart, so automatic sessions or a shared install-daemon setup are preferred for long-lived use. |
errorCode, path, hint | A deploy failure carries its path and remedy, for example the required mkdir -p -m 700 for a missing root outside the home. |
Conflicts
If the remote generated bundle differs from the current bundle, normal deployment does not overwrite it. The panel reports the new or current package version when available and the existing daemon version when available. Otherwise it shows version unknown, plus the backend conflict details.
Only an explicit red Overwrite button authorizes replacement, and the old bundle is retained as a backup. Shared setups configured through daemonSetup or install-daemon are read-only to clients. Clients cannot replace them.
Timeouts
Deployment runs over SSH and can take longer than the dashboard's short status-poll budget. The dashboard gives long actions their own timeout and keeps the printed setup path and load line visible. Do not retry a deploy just because a browser request timed out.
An older daemon on another port is not reused: the daemon probe reports no-listener or legacy. The hint is to deploy, load the returned line in the intended idle CIW and start again.
A reconnect or a plain restart does not deploy files or reload the setup. If the setup was never loaded, run the printed load("...") line first. Reinstall only when the environment, not the CIW, is the proven cause. Runtime covers the lifecycle.
Remote scratch root
The remote scratch root is where deployment, discovery, shells and scripts write. Runtime defaults holds a global default, and a connection's own remoteScratchRoot overrides it. The value reaches helpers as VB_REMOTE_SCRATCH_ROOT, so deployment follows the same root as the runtime instead of falling back to /tmp.
- A leading
~/is expanded on the remote account, and symlinks resolve to the real directory. Every helper and every script or IL upload sees that resolved absolute path. - Prefer an absolute root. Virtuoso
load()does not expand~, so a~-prefixed IL path fails at the firstload(). Sites and packs such as IC23.1 are the usual reason to pin an absolute site path.~/is still accepted and expanded before any upload. - Before any deployment, fixed or automatic, the plugin checks the root. A missing root under the account home is created with mode
0700, with a warning when a sibling path differs only by_versus-. A permissive user-owned root is tightened. A symlink, wrong owner, non-directory or missing path outside the home gets its own actionable error.
| Deploy result field | What it tells you |
|---|---|
configuredScratchRoot | The value as configured on the connection or as the global default. |
scratchRoot | The resolved absolute root actually used for uploads and the load path. |
scratchCreated, scratchTightened | Whether the root was created with mode 0700 or had its permissions tightened. |
warning | Non-fatal notes such as a sibling path that differs only by _ versus -. |
A missing root outside the home is not created. The error names the path and the remedy, for example:
mkdir -p -m 700 /projects/example/.virtuoso-bridge
That message at the first IL load means a ~-prefixed path reached Virtuoso: load() does not expand ~. Set an absolute remoteScratchRoot on the remote account, or leave ~/ and let the plugin resolve it. Deployment and client or IL uploads never pass ~ to load().
Split host roles
Advanced connections can split roles across hosts. Host-key preflight and the SSH test target the primary host. Trust additional role-host keys through ssh and known_hosts before you use a split topology.
| Role | Field | Routes |
|---|---|---|
| Daemon host | daemonHost | The CIW side that runs the bridge daemon. |
| Deploy host | deployHost | Deployment and uploads. |
| GUI host | guiHost | The display and X11 side. |
| Spectre host | spectreHost | The Spectre simulation side. |
The rest of the advanced set maps to upstream split-host, private-scratch and proxy settings: remoteScratchRoot, clientId, sshMaxSessions and a Paramiko sshProxy (socks5://host:port).