Remote execution over SSH

With remote execution over SSH, the files, commands, terminals and confined work of a chat run on a remote Linux or macOS computer while DataMind Oda stays on this computer. This page covers the connection: what it needs, the settings Oda checks, the trust it places in the remote computer, and what happens when it is lost.

What the connection needs

Linux or macOS on both ends. The remote computer and the computer running Oda must be POSIX systems. Starting the connection from a non-POSIX computer is refused with SSH runtime requires a POSIX client.
An SSH host alias that already works. Oda connects through an existing host alias in your SSH setup. It never runs an interactive sign-in, so the alias must already authenticate on its own.
The helper program and its runtime. Install both on the remote computer before you connect, outside the workspace folder and outside its temporary areas. Oda installs nothing there for you.

Connection settings

The connection runs with these settings. Oda checks every value before SSH starts.

Setting	What it is	Default and limits
Host alias	An existing SSH host alias from your SSH setup.	A plain alias; a value that starts with a dash, or carries a command, is refused.
Remote runtime	The absolute path of the Node.js runtime on the remote computer.	Must be an absolute path.
Helper path	Where the helper program is installed on the remote computer.	Must be an absolute path.
Helper digest	The SHA-256 digest of the helper build.	64 lowercase hexadecimal characters; checked before the connection is used.
Workspace folder	The folder on the remote computer that the work runs in.	Must be an absolute path.
Bootstrap path and digest	An optional pair for setups that use a bootstrap.	Set both or neither; an unpaired value is refused.
Request timeout	How long one request may wait.	30 seconds; from 1 ms to 2147483647 ms.
Frame ceiling	The largest single message between Oda and the helper.	64 MiB.
Pending requests	How many requests may be waiting at once.	128.
Lease	How long the remote side keeps the connection's work alive without hearing from Oda.	30 seconds; from 3 seconds to 10 minutes.

A value that fails its check refuses the connection before SSH starts: an option-style host entry or one carrying a command, a relative path, a digest in the wrong form, one bootstrap value without the other, or a number outside its range.

Digest checks and trust

The helper program is versioned, and its digest must match the build you configured before the connection is used. If the installed helper is not that build, the connection is refused with SSH helper digest differs from the configured artifact.

Treat the remote computer and the installed helper as trusted infrastructure. The digest check catches an unexpected installed program; it does not establish a security boundary against a hostile server. Remote sandboxing limits file effects only: it does not restrict network access or process visibility on the remote computer.

What runs on the remote computer

Files, commands and terminals. Oda reads and changes files, runs commands and opens terminals on the remote computer, and their output comes back to the chat.
Confined work. Sandboxing is applied on the remote computer and follows the chat's access mode; in Full access, remote requests run without confinement by design. For the modes, see Workspaces, files and permissions; for denied steps and one-off wider retries, see Command sandboxing and approvals.
How remote files, processes and terminals behave, including lifecycle and errors, is in Remote files, processes and terminals.

When the connection is not ready, closed or lost

While the connection is still starting, a request is refused with SSH helper is not ready. Once it has been closed, requests are refused with SSH connection is closed.

A lost connection is never replayed. Oda cannot know what finished on the remote side, so it reports an unknown outcome instead:

SSH connection lost; remote operation outcome and cleanup are unknown
SSH helper disconnected; remote outcomes and cleanup are unknown

Important

Check the remote computer before you repeat the work.

The helper owns cleanup on the remote side: it cleans up what it started when the connection closes or when the lease runs out. A cancelled operation is not undone either: SSH operation cancelled; a completed remote mutation is not rolled back.

Limits

One message between Oda and the helper is capped at 64 MiB; past that, the call is refused with SSH helper frame or write queue limit exceeded.
128 requests can be waiting at once; beyond that, a request is refused with SSH helper pending request limit reached. The heartbeat and close paths keep their own capacity, so they stay available while many requests wait.
Up to 128 programs and 128 text streams can exist on the remote computer at the same time.
A whole remote read, or one window inside a remote file, is capped at 8 MiB; larger data is read in parts.
POSIX endpoints only. There is no Windows side, Oda does not set the remote computer up for you, and it never reconnects or replays an operation after a lost connection.

Questions, answered

Can the remote computer be a Windows machine?

No. Both sides must be POSIX systems: Linux or macOS. Starting the connection from a non-POSIX computer is refused with SSH runtime requires a POSIX client, and there is no Windows endpoint on the remote side.

Who installs the helper program on the remote computer?

You do, before you connect. Install the helper build and the runtime that runs it on the remote computer, outside the workspace folder and outside its temporary areas. Oda installs nothing there for you.

Why was a connection setting refused before anything started?

Oda checks every value first. The host alias must be a plain alias, the runtime and helper paths must be absolute, the digest must be 64 lowercase hexadecimal characters, the bootstrap path and digest go together, and the numbers must be inside their ranges. A value that fails refuses the connection before SSH starts.

What happens if the helper on the remote computer is not the build I configured?

The connection is refused with SSH helper digest differs from the configured artifact. Install the helper build that matches the digest you configured, or correct the stored digest, and connect again.

Does Oda reconnect and repeat the work after a lost connection?

No. Oda never reconnects or replays an operation. It cannot know what the remote side finished, so it reports an unknown outcome (SSH connection lost; remote operation outcome and cleanup are unknown, or SSH helper disconnected; remote outcomes and cleanup are unknown) and leaves the next step to you: check the remote computer before repeating the work.

Is a cancelled remote operation undone?

No. A cancelled operation is not rolled back: SSH operation cancelled; a completed remote mutation is not rolled back. Check the remote computer for anything that completed before you continue.

What does `SSH helper is not ready` mean?

A request arrived before the connection finished starting, while the helper was still verifying itself. The request was refused instead of run. Wait for the connection to become ready, then try again.

How many requests can wait at once, and how large can one message be?

Up to 128 requests can be waiting at once; beyond that, a call is refused with SSH helper pending request limit reached. One message between Oda and the helper is capped at 64 MiB; past that, it is refused with SSH helper frame or write queue limit exceeded.

What happens if the connection goes quiet?

Oda keeps checking in with the remote side, and the lease setting says how long the remote side keeps the connection's work alive between those checks (30 seconds by default). If the lease runs out, the helper cleans up what it started, and the connection is treated as lost: the outcome and cleanup on the remote side are unknown. Check the remote computer before you continue.