SSH: files, processes and terminals

With SSH remote execution configured, the file, command and terminal work DataMind Oda does happens on the remote computer while the app stays on this one. This page covers how that remote side behaves: files, processes, terminals, confinement, and the codes a failure can carry. The remote computer must be a POSIX system, Linux or macOS; the connection itself, and what to install, are in SSH remote execution.

Remote files

Paths are resolved on the remote computer. Oda resolves every path there, links included, so an operation acts on the file the path really names.
A file's name stays as it is. When Oda identifies a remote file, a name that contains a %, a backslash or a line break is encoded in that identifier, as back\slash.ts becomes back%5Cslash.ts; the file keeps its exact name on the remote computer.
Changes are guarded. A write creates a file only when it is absent, or replaces one only when the version Oda read is still current. A guarded replace that no longer matches is refused with FS_STALE_VERSION.
Watching is not available. A watch request for a remote file or folder is refused with FS_IO_ERROR, without asking the remote side, and Oda does not check the file in a loop instead.
A dropped connection is an I/O failure. If the connection drops during a file operation, the operation fails and is not retried, and a change may already have completed on the remote computer.

Important

After a dropped connection, check the remote computer before you repeat the work.

Reads are capped at 8 MiB. A single read stays within 8 MiB on the remote side, and a whole read that would go past that budget is refused with FS_TOO_LARGE. Read larger files in parts.

Remote commands

The remote side is prepared before a program starts. Oda reserves and authenticates the channels a program needs (input, output, errors and a control channel) before starting it. Each stream is its own channel, so a busy output does not hold up the others.
A start that fails is reported. If a program stops before its start is confirmed, the result reads SSH process terminated before launch acknowledgement.
The end of a program is not the end of its work. A finished remote command reports its exit code, or the signal that ended it. That report does not prove that everything the program started has also stopped; Oda observes that separately, and a wait for the end (waitForExit) resolves only when nothing is left.
Stopping is safe to repeat. Asking to stop the same remote program again changes nothing. If the remote side cannot confirm the stop, Oda reports SSH process cleanup could not be confirmed rather than claim the program stopped.
A program that is not there is a lookup miss. A program Oda cannot find on the remote computer is reported apart from an SSH failure, with SUBPROCESS_EXECUTABLE_NOT_FOUND.
Collected output keeps its positions. A collected result keeps a bounded window of the end of the output, with byte offsets measured from the start of the stream, so Oda can read again from a position it already saw and a completed result does not change when the connection lags.
Large output can stay on the remote computer. When output is large, the full stream can be kept in a private file on the remote computer; such files stay until the computer's own temporary-file cleanup removes them.

Remote terminals

The terminal runs on the remote computer. Shell facts come from the remote side, and a new terminal starts there with the terminal type Oda was asked for.
Activity is idle, busy or unknown. A remote terminal reports what it is doing as idle, busy or unknown, and Oda does not assume a quiet terminal from a missing answer.
Signals. Oda can send SIGINT, SIGTERM, SIGKILL, SIGTSTP or SIGHUP to what is running in a remote terminal.
Resizing does not restart anything. Resizing a remote terminal changes the terminal in place; the shell and anything running in it keep going.
A terminal that cannot be allocated. If Oda cannot allocate a remote terminal and the remote cleanup also fails, the result reads SSH terminal allocation failed and remote cleanup is unknown; treat the remote cleanup as unconfirmed.

The actions for a terminal, and the notes they return, are described in Terminal tools.

Remote confinement

Confinement is applied on the remote computer. When Oda asks for a confined remote command, the remote side resolves the request and wraps the command itself before it can run. If the confinement cannot be applied, the command is refused before it runs, with SANDBOX_UNAVAILABLE, rather than run unconfined by accident.
Full access runs without confinement. In Full access, remote work is not confined, by design. The access modes are described in Workspaces, files and permissions.
What confinement covers. Confinement on the remote side limits file effects only: it does not restrict network access or hide other processes on the remote computer. The remote side states whether it enforces the limits fully or partially, and a partial level stays partial.

For what a blocked command looks like in the chat, and how a wider retry is approved, see Command sandboxing and approvals.

Error codes

When a remote operation fails, Oda reports the code the remote side returned, unchanged. A remote file problem Oda cannot classify further comes back as FS_IO_ERROR, and a cancelled file operation as FS_ABORTED. The common codes:

Code	What it tells you
`FS_STALE_VERSION`	A guarded replace was refused: the file changed since Oda read it. Read the file again, then repeat the change.
`FS_SANDBOX_DENIED`	The remote confinement refused the file change, for example a change attempted under read-only.
`FS_NOT_OBSERVED`	The remote file layer refused the operation with this code; Oda shows it as it came back. Check the file on the remote computer, then retry.
`FS_TOO_LARGE`	A whole read went past the remote side's 8 MiB budget. Read the file in parts.
`FS_IO_ERROR`	An I/O failure: the connection dropped, or a remote file operation Oda does not classify further failed, such as a watch. A dropped connection is not retried.
`FS_ABORTED`	The operation was cancelled before it finished, and is not retried.
`FS_NOT_FOUND`	The remote side does not have that file or folder.
`SUBPROCESS_EXECUTABLE_NOT_FOUND`	The program is not on the remote computer; a lookup miss, reported apart from an SSH failure.
`SANDBOX_UNAVAILABLE`	The remote side could not apply the requested confinement, so the command was refused before it ran.

Connection-level failures, such as a connection that drops or is closed, are described with the connection itself in SSH remote execution.

Questions, answered

Why can Oda not watch a remote file for changes?

Watching is not available over SSH. A watch request is refused with FS_IO_ERROR, without asking the remote computer, and Oda does not start checking the file in a loop instead. Ask Oda to read the file again when you need its current contents.

One of my remote file names contains a `%` or a backslash. Does Oda change it?

No. The file keeps its exact name on the remote computer. Those characters, and line breaks, are only encoded in the identifier Oda uses for the file, as back\slash.ts becomes back%5Cslash.ts.

Why did a remote file operation come back with `FS_IO_ERROR`?

The operation failed at the connection level: the connection dropped, or the operation was a watch request, which remote files do not support. A dropped connection is not retried, and a change may already have completed on the remote computer; check it before repeating the work.

Does a remote command's exit code mean it has finished?

It means the program ended, with that exit code or the signal that stopped it. It is not proof that everything the program started has also stopped; Oda observes that separately, and a wait for the end resolves only when nothing is left. The general rules for the end of a command are in Command execution and Process containment and cleanup.

Is stopping a remote command safe to repeat?

Yes. Asking to stop the same remote program again changes nothing. If the remote side cannot confirm the stop, Oda reports SSH process cleanup could not be confirmed and does not claim the program stopped.

What does `SSH terminal allocation failed and remote cleanup is unknown` mean?

A remote terminal could not be allocated, and the remote side could not confirm that it cleaned up the half-made terminal. Treat the remote cleanup as unconfirmed, and check the remote computer before continuing.

Does resizing a remote terminal restart it?

No. Resizing a remote terminal changes the terminal in place; the shell and anything running in it keep going.

What does `SANDBOX_UNAVAILABLE` mean?

The remote computer could not apply the confinement Oda asked for, so the command was refused before it ran and nothing changed on the remote computer. Retry when the remote side can confine the command; if a step must run without confinement, Full access runs remote work unconfined by design.

What does `SUBPROCESS_EXECUTABLE_NOT_FOUND` mean?

The program Oda tried to run is not on the remote computer. A missing program is reported as a lookup miss, apart from an SSH failure. Install it on the remote computer, or correct the name, then retry.

What do the byte positions in a remote command's output mean?

A completed remote command's output is published as a bounded window of its end, and the byte offsets are measured from the start of the output, so Oda can read again from a position it already saw even if the connection lagged. When the output is large, the full stream can stay in a private file on the remote computer until the computer's own temporary-file cleanup removes it.