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 or private key; authentication comes from ~/.ssh/config, keys, and your agent. The Engine is not a web service: Studio launches a bounded SSH/stdio process for each operation.

Prepare SSH¶

Adapt this ~/.ssh/config entry:

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

Check it in a terminal:

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

The second command proves that a path exists, not that the Studio protocol or physics capability is compatible.

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
Engine executable	`/opt/vma-v07/bin/vm-accelerator-engine`	Remote path/token, with no spaces or shell metacharacters
Connect timeout	`10 s`	1–300 seconds

Orbit v0.9 additionally requires three fields together: a dedicated absolute state directory, an exact 40-character lowercase Engine source revision, and a build ID. If one is set, all three are required. Leave all three empty for an ordinary v0.1–v0.8 target.

A target contains no password, private key, or reconnect token. Removing it does not change the remote host or its jobs.

Two tests with different meanings¶

Test SSH checks authentication and remote-command execution. SSH ready does not mean the Engine was tested.
Test v0.1 Engine negotiates Hello/Capabilities and checks protocol, CPU, permissions, limits, and capability identity.

Specialized v0.7/v0.8/v0.9 pages perform their own exact 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. Nonlinear v0.8 currently requires 5253d675…; orbit v0.9 requires 3b14dbcc…. One executable cannot have both identities, so 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; include v0.9 fields

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.

Normal startup can recover unfinished jobs. --offline disables automatic recovery. If the credential store is unavailable, the remote job may continue, but Studio reports a missing credential rather than inventing access.

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.