跳转至

Connect and Manage an Engine

简体中文 · Previous: Physics inputs · Next: Optics and tracking

Studio uses system OpenSSH to reach a Linux Engine. It stores no SSH password, Authenticator code, or private key; OpenSSH reads its host aliases, keys, and agent configuration. New targets default to a managed tunnel. Studio owns one foreground SSH session, while the bundled headless vm-accelerator-studio-ssh-askpass shim relays OpenSSH prompts over a private per-attempt local channel to an in-application broker and dialog. Answers return only to that OpenSSH attempt and are not persisted. The authenticated session is then reused for Engine RPCs. The legacy per-RPC mode remains available for sites whose SSH login is fully non-interactive.

Prepare SSH

Adapt this ~/.ssh/config entry:

Host vma-engine-v07
    HostName accelerator.example.org
    User beamuser
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

An Engine operator may diagnose the alias in a terminal:

ssh vma-engine-v07 true
ssh vma-engine-v07 command -v vm-accelerator-engine

These commands are optional diagnostics, not an end-user connection step. Studio opens the authentication window itself. The second command proves that a path exists, not that the Studio protocol or physics capability is compatible.

On Windows, install/enable the Windows OpenSSH Client and make ssh.exe available on PATH. Managed mode uses one standard, single-destination local port mapping (-L) and does not depend on -M, -f, -N, or ControlMaster. The same route is used on macOS and Linux; the Engine host remains Linux.

Add an execution target

Open Settings → Execution targets → Add…:

Field Example Meaning
Display name Touschek Engine v0.7 Local human-readable label
SSH host alias vma-engine-v07 Safe OpenSSH host token
SSH connection mode Managed tunnel (interactive MFA) Recommended persistent session; use per-RPC only for prompt-free login
Engine executable /opt/vma-v07/bin/vm-accelerator-engine Absolute remote path in managed mode, with no spaces or shell metacharacters; its directory must contain the environment's python executable
Connect timeout 10 s 1–300 seconds

Orbit v0.9 adds no target fields. Studio supplies its accepted source revision and build ID internally, validates both during the specialized handshake, and lets the Engine select its principal-specific default state root. Existing profiles with an older explicit v0.9 state binding keep using it so retained jobs remain reconnectable.

The reviewed Engine snapshot installer creates the required launcher-and-sibling-Python layout. An arbitrary standalone Engine script is therefore not a complete managed-tunnel deployment.

A target contains no password, MFA response, private key, gateway session token, or job reconnect token. The managed gateway binds only remote 127.0.0.1; Studio's narrow local-forward listener binds only local 127.0.0.1 and maps solely to that gateway. Both ports and the 256-bit session token live only in memory. Disconnecting ends the SSH-owned gateway but does not cancel an accepted durable job. Removing a target does not change the remote host or its jobs.

When Studio contacts a target

Every normal launch is network-idle. Startup, project loading, local journal discovery, target selection, and draft editing do not run ssh -G, start SSH authentication, probe the Engine, recover a pending submission, or reconcile a remote registry.

Every calculation follows this order:

  1. The calculation action opens Choose computation source without contacting any target.
  2. Cancelling closes it with no SSH or remote side effect.
  3. Accepting Check source authorizes Studio to inspect the chosen SSH route, authenticate when needed, and perform the Engine readiness check.
  4. The selected workflow performs its exact capability/project validation before Evaluate or Submit. A generic Engine check does not make every specialized route compatible.

Two tests with different meanings

  1. In managed mode, the explicit Connect action presents each OpenSSH authentication prompt through the in-application dialog, then keeps the private tunnel and per-user gateway alive. Connected still does not mean the Engine protocol was tested. Disconnect releases this session. In legacy mode, Test SSH checks prompt-free authentication and remote-command execution.
  2. Test Engine automatically connects first when needed, then negotiates Hello/Capabilities and checks protocol, CPU, permissions, limits, and capability identity.

A site that requires a new Authenticator code for every SSH login asks once per managed Studio session instead of once per RPC. Losing the network or disconnecting the tunnel requires a new authentication sequence on the next Connect or Test Engine attempt.

Cancelling a source chooser starts nothing. Cancelling an active authentication prompt, an SSH startup timeout, or Disconnect invalidates that attempt immediately in the UI; Studio retires the owned configuration/SSH processes asynchronously, first requesting termination and then killing them after a bounded grace period. The UI does not wait synchronously for a process to exit, and a late message from a retired attempt cannot make it ready.

Specialized v0.7–v0.18 pages perform their own exact capability, source, and deployment checks. A successful v0.1 test does not make every higher route available.

Separate targets for incompatible exact builds

Some formal routes require an exact source revision. An executable has one source identity; do not overwrite several accepted versions behind one target. Use separate profiles, for example:

Display name Executable Purpose
Engine nonlinear v0.8 /opt/vma-5253/bin/vm-accelerator-engine Durable nonlinear
Engine orbit v0.9 /opt/vma-3b14/bin/vm-accelerator-engine Durable orbit; identity checked automatically
Engine native v0.11–v0.17 /opt/vma-ecd9/bin/vm-accelerator-engine Attached-Xsuite exact-source one-shot analysis
Engine nonlinear v0.18 CUDA /opt/vma-e967/bin/vm-accelerator-engine One-GPU Slurm/CUDA durable nonlinear

Use builds approved by the Engine operator. A later commit must not be assumed compatible.

Job credentials and restart recovery

After a durable job is accepted, Studio stores a non-secret bookmark and places the reconnect token in macOS Keychain, Windows Credential Manager, or Linux Secret Service. Tokens never enter .vmaproj, project JSON, or normal settings.

Startup reads bookmarks and pending journals locally but does not connect, recover, or reconcile automatically. An explicit pending-recovery action first asks for operator confirmation. Only after confirmation does Studio connect to the target recorded in the journal and replay the exact request with its original idempotency key. Recovery never offers another computation source. If the action is cancelled, no connection is started. If the credential store is unavailable, the remote job may continue, but Studio reports a missing credential rather than inventing access.

--offline keeps an explicit offline policy/status for a review launch; normal startup is already network-idle. Do not invoke an explicit remote action when the entire session must stay offline.

Detach, abort, and cancel

  • Detach: stop observing; the durable remote job continues.
  • Abort client: terminate a one-shot client/SSH process; this is not durable Engine cancellation.
  • Cancel request: request cooperative cancellation. Request acceptance, worker confirmation, and terminal cancellation are distinct states.

Closing Studio does not automatically cancel accepted durable jobs.

Operator handoff checklist

Provide the SSH alias, Engine executable, supported workflows, exact source/build, required state directory, principal permissions, and expected resource/time envelope. “SSH connects” alone is not an Engine-readiness result.