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.
- The mirror lives in the state directory of the compute machine. When the environment directory is a Git checkout, the mirror holds the files Git can see; ignored files are not synchronised and
.gitis not mirrored. - A sync runs before and after every turn, and before and after every
ail shell. Commands on the environment, and the engine, therefore always see the files as the agent changed them. ail getandail putfetch and place single files between the local machine and the environment, regardless of ignore rules.- A sync conflict fails the turn with
SYNC_CONFLICT, and the agent decides which side wins.
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:
- No waiting for input. The command's standard input is closed; a command that reads input gets EOF at once.
- A timeout kills the whole process tree. A Job Object on Windows, the process group on Linux.
- Encoding is always UTF-8.
- No substitution. If the requested shell is missing on the target, the error is
SHELL_NOT_AVAILABLE; the other shell is never used instead. - The command runs as the user the Daemon runs as.
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.