SSH remote execution

With the SSH option, a chat's files, commands, terminals and sandboxing run on a remote Linux or macOS computer over SSH, while DataMind Oda stays on your computer. This page is the reference for the connection: what it needs, the settings Oda checks, the messages when it is lost, and the limits that apply. The behaviour of remote files, processes and terminals is on SSH: files, processes and terminals.

What the connection needs

Three things must be in place before the connection starts:

Linux or macOS on both computers. The remote computer and the computer you run Oda on 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 SSH host alias and never runs an interactive sign-in, so the alias must 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 the computer's temporary areas. Oda does not install them for you.

Connection settings

The connection uses these settings. Every value is checked before the connection 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	The absolute path of the helper program 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 chat works 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.
Frame ceiling	The largest single message between Oda and the helper.	64 MiB.
Pending requests	How many requests may wait at once.	128.
Lease	How long the remote side keeps the work alive without hearing from Oda.	30 seconds, from 3 seconds to 10 minutes.

A value that fails a check refuses the connection before SSH starts: a host alias with a leading dash or a command in it, a relative path, a digest in the wrong form, one bootstrap value without the other, or a number out of range.

Digest checks

The helper program is versioned, and its digest must match the build you configured before Oda uses the connection. If the installed helper is not that build, the connection is refused with SSH helper digest differs from the configured artifact. A setup that uses the bootstrap pair is refused too until the pair is set and verified.

The check catches an installed program that is not the build you configured. It does not make a remote computer safe to run work on: treat the remote computer and the installed helper as trusted infrastructure, because digest checks and the sandbox do not establish a security boundary against a hostile server.

How the remote side behaves

Files. Reads and changes stay inside the workspace folder on the remote computer. Writes are guarded: a write creates a file only when it is absent, or replaces one only while the version Oda read is still current.
Commands and terminals. Oda runs its commands and opens its terminals on the remote computer, and their output comes back into the chat.
Sandboxing. The sandbox runs on the remote computer, following the chat's access mode; for the modes, see Workspaces, files and permissions. In Full access, remote requests run without limits by design. For blocked steps and one-off wider retries, see Command sandboxing and approvals.
Cleanup. The helper owns what it started on the remote computer. It cleans up when the connection closes, on termination signals, or when the lease expires.

When the connection is lost

Two messages mark the state of the connection: SSH helper is not ready while it is still starting, and SSH connection is closed after it has been closed.

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

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

A cancelled operation is not rolled back either: SSH operation cancelled; a completed remote mutation is not rolled back. If the remote side cannot confirm its cleanup, Oda reports SSH process cleanup could not be confirmed.

Important

Check the remote computer before repeating an interrupted operation.

Limits

One whole read, or one window inside a remote file, is capped at 8 MiB; larger data is read in parts.
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 wait at once; a request beyond that is refused with SSH helper pending request limit reached.
Up to 128 programs and 128 text streams can exist on the remote computer at the same time.
Linux and macOS only. There are no Windows endpoints, Oda sets nothing up on the remote computer for you, and it never reconnects or replays an operation after a lost connection.
The sandbox limits file effects on the remote computer; it does not restrict network access or process visibility there.

Questions, answered

What does Oda check before it starts the connection?

Every connection value is checked first: the host alias must be a plain alias, the runtime and helper paths must be absolute, the helper digest must be 64 lowercase hexadecimal characters, a bootstrap value must come with its pair, and the numbers must be inside their ranges. A value that fails refuses the connection before SSH starts, so nothing reaches the remote computer.

Do I need the bootstrap pair?

Only for setups that use a bootstrap; basic file and command work does not need it. The bootstrap path and its digest go together: set both or neither. A bootstrap-backed setup is refused until its pair is set and verified.

Does the digest check protect against a hostile remote computer?

No. It catches an installed helper that is not the build you configured, which is its purpose: the remote computer and the helper are treated as trusted infrastructure. Digest checks and the sandbox do not establish a security boundary against a hostile server.

Who cleans up the programs a chat started on the remote computer?

The helper. It cleans up what it started when the connection closes, on termination signals, or when the lease expires. Cleanup happens on the remote side, so a lost connection reports an unknown outcome instead of a confirmed one.

What does "SSH helper is not ready" mean?

A request arrived before the connection finished starting: the helper has not yet verified itself. The request is refused rather than run; wait for the connection to become ready and try again.

How many programs and streams can run on the remote computer at once?

Up to 128 programs and 128 text streams at the same time. Separately, up to 128 requests can wait at once; beyond that a request is refused with SSH helper pending request limit reached.

Why does Oda not retry an operation after the connection is lost?

Because it cannot know whether the operation finished. The remote side may have completed a change before the connection dropped, and a completed change is not rolled back. Oda reports an unknown outcome instead of repeating the work; check the remote computer before running it again.

Why can a remote write be refused after the file changed?

Because writes are guarded: a replace goes through only while the version Oda read is still current. When the file changes first, Oda reads it again and then makes the change.