05 · Architecture
Runtime lifecycle and internals
A managed runtime binds one SSH (Secure Shell) forward, one Python sidecar (a helper process per runtime) and one daemon inside the Virtuoso CIW (Command Interpreter Window) under a single runtime id. The Host — the plugin's Node.js half — owns that bundle, not the conversation. Runtimes live in the plugin process, outlive the session that started them, and appear in the right-sidebar panel. This chapter shows what each state means, who owns the tunnel, what the helpers inherit, and where files land.
States and objects
The runtime state answers one question: can this connection be used right now? Action status reports it in a compact projection. A start returns the same snapshot, and the panel renders that value.
| State | Meaning |
|---|---|
stopped | No runtime exists: there is no forward and no sidecar process. |
starting | The tunnel and the sidecar are starting. |
connecting | The sidecar is connecting to the daemon, or deploying for it. |
waiting | The tunnel is up, but the daemon does not answer yet. |
running | The daemon answers. execute_skill("1+1") returned through it. |
error | A start, a health check or a runtime operation failed. |
needs-trust | The host offered an unknown SSH key. The runtime stays stopped until you confirm the fingerprint. |
A stop is a brief transition. While the runtime tears down its workers, sidecar and forward, its snapshot state is stopping. It is not a resting state.
Daemon and connection status
A state tells you that a connection broke, not where. Every snapshot therefore carries a separate daemon object, and the panel shows it as its own chip next to the connection state. Startup records it from the connect handshake. Test probes it even when the runtime is stopped.
| Daemon status | What it proves |
|---|---|
ready | A signed bridge daemon answered the capability handshake. |
no-response | The daemon port is reachable over TCP, but the bridge behind it does not answer. |
auth-failed | A bridge daemon is present and refuses this client's token. |
unreachable | Nothing answers on the configured daemon port. |
unknown | No probe has produced a verdict yet. |
The same values appear as connectionStatus in the runtime snapshot: ready, no-response, auth-failed, unreachable or unknown. A separate daemonProbe reports the deployment-side verdict: no-listener, legacy, and whether the daemon is signed. That verdict decides whether the remedy is a deployment.
Attaching to a signed daemon
A fixed-port start probes the daemon port before it deploys anything. If this account's daemon answers with a signed capability handshake, the runtime attaches to it and skips deployment, reporting attach.attached and the reused setup path. The scratch root is not prepared in that case, so a broken root cannot block a live instance. See Attach before deploy for the connection-side view.
Lifecycle
start opens the managed forward and connects the sidecar. restart repeats that sequence, and subInstance selects a configured workdir sub-instance. status with waitMs waits for an in-flight start to settle, so you do not get a bare starting snapshot. A fixed-port start may end in waiting on purpose. The network side worked, and the CIW has not loaded the prepared setup yet.
A reconnect or a plain restart does not deploy files, and it does not reload the setup in the CIW. Only deploy_daemon prepares the bootstrap. Loading it stays a human act in the intended idle CIW.
The health loop
Every 20 seconds, the Host health loop requests a status from the sidecar of each running, waiting or error runtime. The loop writes nothing to the CIW: log_to_ciw=False unless settings.logToCiw is enabled. It also catches a missed child-process event, so a forward that exited without a notification is still noticed.
A responsive daemon moves a waiting runtime to running. It also records the remote project working directory and clears the setup hint. A running runtime that stops answering falls back to waiting, where dialog inspection picks it up.
Dialog inspection
When the daemon does not answer, the Host inspects X11 dialogs and records the report in the snapshot. The status carries the dialog title, the panel shows a warning, and the hint tells you to click or answer the dialog in Virtuoso, then refresh. The hint never asks for a daemon reinstall or a setup reload. Inspection is skipped when the daemon probe already reports no-listener, where no dialog can be the cause.
If a daemon was healthy and then stops answering, the panel reports a daemon-lost reason instead of the initial setup hint. The setup did load once, so look at the CIW itself.
Process-wide runtimes
Runtimes are process-wide. They survive conversation changes, forks and subagent sessions, and every conversation in the profile talks to the same live bridge. They stop when you disable or unload the plugin, when DSH exits, or when you run action stop.
A crashed process can leave an orphaned forward behind. The plugin finds it from the virtuoso-bridge state file and its own tunnel record. orphans lists them, stop_orphan stops one, and the runtime panel exposes the same control.
The Host-owned tunnel
The Host opens the SSH forward for fixed-port remote connections. It does not leave that job to the Python sidecar, which would start a free-running ssh.exe. Owning the child gives the plugin its readiness signal, its port choice and a single forward that every helper adopts. The rest of this section describes that design.
The ssh child
lib/tunnel.js spawns ssh -N -L as a hidden, non-detached child and tracks it from child-process events.
ssh -v -N -L 65123:127.0.0.1:65123 -l designer virtuoso01.example.com
The real command also passes -o BatchMode=yes, a connect timeout, ControlMaster=no / ControlPath=none / ControlPersist=no, ExitOnForwardFailure=yes and ServerAliveInterval=30 with ServerAliveCountMax=3. It adds -F for the generated config, -i for an identity file and -J for a jump host.
Non-detached is deliberate. On Windows, a hidden non-detached child keeps a hidden console, and its implicit ProxyJump or ProxyCommand child inherits it. Detaching the tunnel made that grandchild open a visible console window.
Readiness comes from OpenSSH's own verbose log line, Entering interactive session. The plugin does not dial the forward port to learn that. A dropped tunnel is reported immediately from the child's exit.
Local port allocation
The plugin allocates the local port with a bind test on both loopback families. OpenSSH binds the -L listener for IPv4 and IPv6 loopback, so a port that is busy only on ::1 is not usable. connection.localPort is honoured when that port is free. If OpenSSH still loses the race, the start retries on another port instead of failing the runtime.
The adoption shim
The sidecar and every script helper receive VB_PLUGIN_TUNNEL_OWNER=plugin, the tunnel PID, and the local and remote ports. runtime/vb_plugin_env.py installs an adoption shim in isolate_runtime_env(). Upstream SSHClient then adopts that forward, answers liveness from the PID, and raises instead of starting a second ssh.exe. The shim is installed before a script body runs, even when the script never calls connect(). Test and health helpers refuse to create a forward without the Host switch, and tunnel teardown belongs to the Host.
ssh.exe does not multiply with scripts, health checks or connection tests. A script also cannot tear down the forward that the sidecar is using.
Discovery before the forward
A small record under the data directory's tunnels/ keeps a Host-owned forward discoverable after a crashed DSH process. The panel shows the tunnel state, its PID, and the localhost:port → remote pair.
Automatic-session connections run the same read-only instance discovery as the instances action, before the tunnel opens. The Host then forwards to the instance the sidecar will select. An ambiguous discovery — several live instances, no stored selection — fails with the available list instead of forwarding to the wrong CIW.
Panels and endpoint
Two panels, one same-origin endpoint. Both surfaces read the same state, and neither keeps a second copy of it.
Configuration page
The left sidebar entry opens the full-page configuration view, which starts on Server connections. Environment, runtime defaults, storage and activity stay folded until you need them. Environment setup, with its source and install log, is disclosed only when expanded or unhealthy. This page owns the long-lived controls: install and repair, the connection cards, credentials, workdir sub-instances, and the cache directory.
Runtime panel
The right tab is fixed to dsh-virtuoso-bridge. It contains:
- Environment, shown only while setup is not ready, with an Open settings prompt.
- Server connections, each with Start/Stop, a status and a details disclosure.
- Agent activity: the current session's agent is pinned at the top and highlighted. Each agent folds its own history, running tools stay visible, and inactive agents remain listed in gray.
- Connection pills, on the same line as Last used: one per server the agent has connected to. A server inactive for more than 10 minutes turns gray. After 30 minutes it leaves the pills only, and the agent row remains.
- Storage: a one-line size and free-space summary. The full path, size and clear list live on the configuration page.
A single click toggles an agent's history. A double-click opens that DSH session in the main view.
Composer control
The composer control is the VB mark plus a status dot, with no text. It is green when connected, yellow when waiting or blocked, and red on error. It breathes green while a call for that session is running. The control is absent while the Session has no active runtime (running, waiting, starting or connecting), so a Session without a bridge keeps the composer clean.
Dashboard endpoint
Both surfaces read the same-origin endpoint /__dsh/virtuoso-bridge over an SSE stream. The Host registers the route through ctx.inject(['webServer']), so the route still exists on a cold boot where the webserver activates after feature plugins.
The browser half bootstraps { token, origin, basePath } from a loopback-only /bootstrap. It tries the injected origin first, then the page's own origin, and retries after a 404 or a stale token. The endpoint requires the per-process token or a local same-origin request. Cross-site requests are rejected even when they arrive from 127.0.0.1.
Binding the Web server to a non-loopback address widens exposure of the whole DSH UI, not just this endpoint. Keep the default loopback bind. Reload the page after upgrading the plugin so the browser uses the current bundle.
Isolation
A runtime must not inherit what you or another bridge installation saved earlier. The plugin enforces that at the process boundary. The connection-side rules are in Credentials and authentication.
Runtime environment
The plugin never copies your ~/.virtuoso-bridge/.env. Every Python helper is isolated from it with the plugin's empty runtime env file before virtuoso_bridge is imported. That covers deploy, discovery, SSH test, sidecar, shell probe and scripts, so the saved connection is authoritative for that runtime. Helpers start from the plugin venv with -E -s. They inherit no PYTHONPATH, PYTHONHOME or VIRTUAL_ENV, and no ambient VB_* values. A second local virtuoso-bridge installation cannot redirect a plugin call.
Venv guard
The venv probe refuses to report ready when the imported virtuoso_bridge comes from outside the plugin venv. The one exception is an explicitly configured editable local checkout, where the venv is deliberately pointed at that source.
Generated SSH config
The generated per-runtime SSH config is content-addressed by profile and by a digest of the connection's SSH-relevant fields. A tool call therefore cannot delete or rewrite the config file a running tunnel uses. Editing a connection produces a new file, and the live forward keeps its own.
Daemon tokens live in the DSH credentials service as a grant record. They are write-only in the UI and passed to the sidecar through its environment. They never reach connection JSON or logs, and the panels never return them.
Data, cache and storage
The plugin keeps durable state apart from disposable artifacts. The data directory holds what the runtime needs to start again, and the cache directory holds what can be rebuilt or cleared. Both paths, and their overrides, are described in Data directory.
| Item | Location |
|---|---|
| Python venv | Data directory |
settings.json and plugin logs | Data directory |
Installed bridge documentation: skills/, README.md, AGENTS.md | Data directory, instructions/ |
| Tunnel records for Host-owned forwards | Data directory, tunnels/ |
| pip wheels, git checkouts, script jobs, large results | Cache directory |
Leave the cache path blank to use the data directory. Changing it does not move existing files, and the runtime panel immediately shows the new paths.
Storage on the configuration page lists each cache with its label, path, byte size, file count, free space and a per-item Clear control. The right panel keeps only the one-line size and free-space summary.
Next
The operations chapter turns these internals into decisions: which state to trust, when to deploy, and what to send when a problem survives the checklist.