Skip to main content

​
Executions, output, and files

sandbox exec creates one supervised execution and prints its ID before dispatch. The sandbox execution commands address that exact (sandbox, execution) pair without starting another command.

​
Reconnect and replay output

Use attach --after-cursor CURSOR to replay supervisor-retained output after the last accepted cursor, then follow live output. Retention is bounded rather than permanent command history. status, wait, and cancel return content-free execution state. An authorised child receives its process capabilities and can deliberately print a mounted environment or GitHub secret. During uninterrupted streaming, the CLI returns stdout and stderr verbatim to the connected caller, whose terminal or agent runner may record it. Avoid env, printenv, shell tracing, and echoing GH_TOKEN; avoid printing secrets into retained output. If an attached connection is interrupted, use the printed execution ID to query status first. Do not rerun an arbitrary command to discover whether it started.

​
Incomplete output after a reconnect

In Aient CLI 0.11.29, sandbox exec and sandbox execution attach report when a reconnect resumes after output the server no longer retains. While the client stays connected, the command runs at the client’s pace, including when a pager pauses reading. If output is missing:
  • stdout keeps only the bytes received before the gap;
  • the retained tail goes to stderr between an aient: output incomplete: bytes FROM-TO lost; ... header and an aient: output incomplete: end of retained tail line; and
  • the CLI exits with status 74 when it receives the terminal result. The header reports the command’s own outcome, including its exit code when known.
With --json, the CLI emits an execution_output_gap event and also exits 74 at the terminal result. Treat the output as incomplete even if the command itself succeeded. Keep the retained tail for diagnosis, and use the execution ID with status or wait to inspect the command’s outcome. Reattaching cannot restore bytes that are no longer retained; only rerun a command if repeating its effects is safe.

​
aient sandbox execution status

Copy the execution UUID printed by sandbox exec into a shell variable:
Then read the current content-free state, repeating the original authority selectors:

​
aient sandbox execution attach

Attach to output from a known execution:
Add --after-cursor CURSOR to replay retained output after the last accepted cursor. Cursor acceptance is frame-atomic, so reconnect may repeat the last complete frame without creating an output gap or starting another command. Use sandbox run --detach --keep or sandbox exec --detach when the command must outlive its initiating client.

​
aient sandbox execution wait

Wait for the terminal outcome without receiving output:
Add --json for structured state. A terminal result can report a known exit code, cancellation, or an unknown outcome; the CLI does not guess by replaying the command.

​
aient sandbox execution cancel

Explicitly cancel the exact execution:
Cancellation does not delete the sandbox.

​
Environment and repository selectors

All four execution-observation commands accept: Use the same selectors as the original environment-capable sandbox exec.

​
Explicit file commands

File commands address an existing sandbox without an environment binding and an explicit path. They are separate from exact Git workspace synchronisation. They cannot carry the selectors required to address an environment-bound customer sandbox.

​
aient sandbox files put

Upload one file or directory into an absolute remote directory:
Directory excludes support /-separated *, **, and ? globs. The CLI rejects upload of the active access-token file, including hard links to that file.

​
aient sandbox files get

Download one explicit remote file:
Directory download is not part of this command.

​
aient sandbox files ls

List an absolute remote directory:
Without a directory argument, the CLI lists /.

​
aient sandbox files rm

Remove one explicit remote path:
files rm changes the remote filesystem immediately. Verify the sandbox and absolute path before running it.

​
Agent worktree reads

Use agent worktree read when you need one exact baseline from an Agent’s existing attached repository worktree. It is read-only: it does not create a sandbox, change Agent ownership or retention, or edit the worktree.
PATH is relative to the named attached repository’s worktree. The command accepts one regular, single-link file up to 64 KiB and records its raw bytes, type, mode, and SHA-256. It rejects symlinks, .git paths, protected paths, and larger files. The destination must be new. Its existing parent must be owned by you and not writable by group or others. Aient writes the JSON artifact with mode 0600 and prints metadata rather than file content. The resulting artifact is a historical snapshot of the exact admitted binding, not a write grant or proof that the Agent still uses that worktree. The command needs both aient.agent.read and aient.sandbox.files grants, plus a CLI and server version that support the reader. If the binding changed, request a new read instead of treating an older artifact as current.

​
Workspace mutation fencing

Workspace reads and commands participate in a shared fence; sync activation and direct workspace mutation require the exclusive form. A file command against a busy workspace currently fails closed rather than waiting. If you see a workspace-busy response:
  1. Do not loop concurrent mutations.
  2. Check or wait for the known execution using its ID.
  3. Retry the file operation only after the reader or mutation has finished.
Never interpret partial transfer progress as a completed file installation. Explicit files put remains bounded by the total --timeout duration. The progress-sensitive inactivity budget described for sandbox sync does not apply to arbitrary file uploads.