All docs

System

Across machines

Compute apart from environment, remote workspaces, and running PowerShell or Bash on another machine.

Compute and environment

A session has two "wheres". They are fixed when the session is created and do not change:

Name What it is
Compute The Client on which the session's harness is started
Environment Where the session works: a Client and a directory on it
Session Compute Environment
Author or reviewer of a workflow step The Client the role is bound to The Client that holds the run's Repo; the directory is the Repo's main checkout
A session you open directly The harness on the Client you pick The Client and folder you pick

When both are the same machine it is a local session; when they are not, it is a remote workspace. To the engine, the UI and the Router, both are the same Worker.

So a machine without a harness can still hold a repository to work in. And when someone else's machine has just one harness installed, binding a role to it lets the Desk drive it asynchronously.

Remote workspaces

The compute machine holds a mirror of the environment directory. The agent reads, searches and edits the mirror with the harness's own tools; commands (tests, builds, Git) run on the environment machine through ail shell, and files are synchronised both ways before and after.

A mirror was chosen over "read and write every file across the network" because reading, searching and editing stay local: however large the latency, only a few commands cross the network.

Non-interactive execution

ail shell runs one PowerShell or Bash command on a Client. The caller hands the request to the Desk; the Desk authorizes it and forwards it to the target Client's Daemon; the result comes back the way it went.

ail shell --target home-server --shell bash "uname -a"

Commands that contain quotes, $ or newlines go through standard input and arrive byte for byte:

ail shell --target home-server --shell bash --stdin <<'EOF'
df -h / | tail -1
EOF

Request fields:

Field Meaning
target The id of the target Client. When omitted, the Client that holds the calling session's environment
shell powershell or bash
command The command text, passed to the shell as it is
cwd Optional working directory on the target
timeout_s Optional; 30 by default, 600 at most

Result fields:

Field Meaning
ok Whether the request was executed. It stays true when the command itself fails with a non-zero exit code
exit_code The exit code; 124 on timeout
stdout, stderr UTF-8 text, at most 64 KB each
duration_ms, timed_out, truncated Duration, whether it timed out, whether output was truncated

Rules of execution:

The command line waits at most 8 seconds. If the command has not finished it returns pending; the command runs to its end on the target and the result is fetched with ail op.

Who may use which shell on which Client is decided by the authorization rules in the Desk, deny by default.

Interactive consoles

On the new session page you pick a Client, a folder and PowerShell or Bash, and get a terminal tab. The Daemon opens a pseudo-terminal locally and the byte stream travels through the Desk to the browser. Only you can open a console; agents have non-interactive execution only.