Loading the documentation…

SSH remote execution

With an SSH host configured, DataMind Oda can run files, commands, terminals and confined work on a remote computer over SSH, while the app itself stays on this computer. Use it when the work belongs on another machine, such as a shared build server. This page covers what the connection needs, how it is configured, and what happens when it is lost.

What you need first

Linux or macOS on both computers. This works between POSIX systems: the remote computer and the computer you run Oda on. Starting it from a non-POSIX computer is refused with SSH runtime requires a POSIX client.
A Node.js runtime and the helper program on the remote computer. Install both before you connect, outside the workspace folder and outside the computer's temporary areas. Oda does not install them for you.
An SSH host alias that already works. Oda connects through an existing SSH host alias on this computer and never runs an interactive sign-in, so the alias must already authenticate on its own.

Connection settings

Oda connects with 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	Where the helper program is installed on the remote computer.	Must be an absolute path.
Helper digest	The SHA-256 digest of the helper program.	64 lowercase hexadecimal characters; checked before the connection is used.
Workspace folder	The folder on the remote computer that Oda 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; 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 in flight at once.	128.
Lease	How long the remote side keeps the connection alive without hearing from Oda.	30 seconds, from 3 seconds to 10 minutes.

A value that fails a check refuses the connection before anything 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 one you configured before Oda uses the connection. If the installed helper is not the build you configured, 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.

Treat the remote computer and the helper as trusted infrastructure. The digest check catches an unexpected installed program, and confinement limits what Oda does to files. Neither guards against a hostile server, and confinement does not restrict network access or process visibility on the remote computer.

What runs on the remote computer

Files. Oda reads and changes files on the remote computer. Writes stay inside the workspace folder and are guarded: a write creates a file only when it is not there yet, or replaces one only when 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 to the chat. If a remote program stops before its start is confirmed, Oda reports SSH process terminated before launch acknowledgement.
Confined work. Confinement is applied on the remote computer. File work follows the chat's access mode, and in Full access remote requests run without confinement by design. For blocked steps and retries, see Command sandboxing and approvals.

For more on how remote files, processes and terminals behave, see SSH: files, processes and terminals.

Limits

A single whole read, or a 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 be pending at once; a request beyond that 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 be open on the remote computer at the same time.
POSIX endpoints only. There is no Windows side, Oda does not install anything on the remote computer, and it does not reconnect or repeat an operation after a lost connection.

When the connection is lost

While the connection is still starting, a request is refused with SSH helper is not ready; after it is closed, with SSH connection is 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

Important

Check the remote computer before you repeat the work.

Cleanup on that side is the helper's job: it cleans up what it started when the connection closes, when the stream ends, on termination signals, or when the lease expires. 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.

Questions, answered

Which systems can I use SSH remote execution with?

Linux and macOS: both 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, and there is no Windows endpoint on the remote side.

What must I install on the remote computer?

A Node.js runtime at an absolute path, and the helper program, both outside the workspace folder and outside the computer's temporary areas. Oda does not install them for you.

Does Oda ask me for my SSH password?

No. Oda connects through the host alias on its own and never runs an interactive sign-in, so the alias must already authenticate without prompting.

What happens if the connection drops while something is running?

Oda 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 never reconnects or repeats the operation, because it cannot know whether the remote side finished. Cleanup on that side is the helper's job. Check the remote computer before running the work again.

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.

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.

What happens to a remote command I cancel?

It is not rolled back: SSH operation cancelled; a completed remote mutation is not rolled back. A cancelled operation is not undone, so check the remote computer for what completed before you continue.

Can Oda change files outside the workspace on the remote computer?

File changes stay inside the workspace folder, and they are guarded: Oda creates a file only when it is absent, or replaces one only when the version it read is still current. When the file changed first, the write is refused, and Oda reads it again before making the change. In Full access, remote requests run without confinement by design.

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 (set both or neither), and the numbers must be inside their ranges. A value that fails refuses the connection before SSH starts.

Why does Oda check the digest of the helper program?

The helper is versioned, and the digest shows that the installed program is the build you configured. If it is not, the connection is refused with SSH helper digest differs from the configured artifact: install the helper build that matches the digest, or correct the stored digest, and connect again. The check guards against an unexpected installed program; it is not a defence against a hostile server.

How large can one remote read be?

Whole reads and windows inside a file are capped at 8 MiB each; larger files are read in parts. A single message between Oda and the helper is capped at 64 MiB, and up to 128 requests can wait at once.