Run and synchronise workspaces
Workspace transfer and repository authority are separate:- Workspace source is the exact local checkout or linked worktree transferred into the sandbox.
- Repository authority is the server-verified GitHub repository against which brokered provider credentials and repository-scoped policy may be used.
aient sandbox run
Create a sandbox, optionally transfer a workspace or upload, run one command, and delete the sandbox:
--environment, --workspace defaults to the current directory. With --workspace, the remote directory defaults to /workspace/repo, and the command runs there unless --workdir overrides it.
Use exact argv after --:
--shell when shell syntax is required. Aient CLI 0.11.26 and later use Bash for --shell and --stdin; arguments after -- remain literal:
Workspace and authority flags
Repository candidates are inferred from sanitised
origin and upstream remotes when possible. Embedded remote credentials are not transmitted or displayed. If exactly one authorised repository matches, Aient binds it automatically. If none match, ordinary offload may continue without GitHub access. Use --repository when candidates are ambiguous.
Changing a local remote cannot grant repository access. Every provider operation is re-authorised against the authenticated organisation, active GitHub App installation, and current repository permissions.
Git SSH trust bootstrap
By default,sandbox run selects SSH hosts only from the chosen repository’s origin, upstream, and root .gitmodules. It copies matching public records already present in the host user’s standard known_hosts files and atomically merges them into the sandbox user’s ~/.ssh/known_hosts. Existing unrelated sandbox entries are preserved.
This never copies private keys, SSH configuration, an SSH agent/socket, credentials, or the complete host trust file. When github.com is selected, the sandbox user’s Git configuration also rewrites the common GitHub SSH URL forms to HTTPS, where an authorised repository-capability-bearing command can use Aient’s request-local scoped credential. Other SSH hosts receive trust only; they still need their own sandbox-available authentication.
If local trust is absent or the sandbox runtime cannot install it, Aient prints a warning and continues creating the sandbox. Use --ssh-known-hosts=none when repository policy requires the image-provided trust state to remain unchanged.
Selected nested repositories
The default workspace policy rejects initialized submodules instead of silently transferring or omitting their checked-out bytes. If the command does not consume child repository content, use the explicit Gitlink-only policy:sandbox sync:
/workspace/repo containing the exact root
Git state and only the explicitly selected child snapshots. Every unselected
Gitlink remains an empty ordinary boundary, even when its local checkout is
initialized or dirty; those bytes are not transferred, preserved, or treated
as implicit input.
Each selected child must be an ordinary initialized repository, clean and at
the exact final parent-index Gitlink OID, with complete local history and no
replacement refs. To select a nested descendant, repeat --submodule for the
complete ancestor closure, using canonical paths from the top-level repository.
Aient does not recursively discover descendants. The first selected protocol
generation accepts at most 64 selected repositories and 512 Gitlink boundaries
across the selected tree.
--submodule without --submodules=selected, selected mode without a path,
unsafe or duplicate paths, incomplete ancestry, and a custom remote root all
fail before publication. Selected mode is fixed to /workspace/repo. A
retained sandbox whose reader predates selected-submodule support returns
workspace_layout_selected_submodules_unavailable; recreate or upgrade it
rather than retrying with a broader transfer policy.
Command and lifecycle flags
--upload PATH uploads a non-Git file or directory instead of synchronising Git state. It excludes .git and node_modules by default. Do not combine --upload and --workspace.
--env and --metadata are non-secret inputs. Metadata is ordinary control-plane state: never put tokens, credentials, or sensitive values in it. It cannot override server-owned organisation, actor, environment, or repository identity.
Environment and GitHub credentials are injected only into an authorised sandbox process. Raw credentials are not returned as OAuth, profile, operation-result, metadata, or workspace-revision fields, and generic file APIs do not project mounted secrets. The CLI does not retain normal command output. An authorised child can nevertheless deliberately print or copy a mounted secret; stdout and stderr are returned verbatim to the connected caller, child-created files can contain those bytes, and either may be captured by its terminal or agent transcript. Avoid env, printenv, shell tracing, or echoing GH_TOKEN.
Use
sandbox run --detach --keep when a command must outlive the initiating client. Keep its execution ID so you can inspect, attach to, wait for, or cancel that same command. See Executions, output, and files.aient sandbox sync
Synchronise exact local Git state into an existing sandbox:
/workspace/repo. For an environment-bound customer sandbox, repeat the original environment and repository selectors:
sessionId. Aient CLI 0.11.22 reuses shared Git history for eligible native V3 workspaces during sandbox sync and sandbox exec --workspace. A workspace-backed command starts only after activation succeeds.
/ separators and support *, **, and ?.
Excludes filter only the explicit non-Git layer and cannot remove tracked Git state. With one or more --include patterns, they subtract from those selected paths. With no --include, exclude-only mode starts from the complete ignored and untracked inventory, then subtracts every matching path. This broad mode has no implicit cache or secret exclusions, so explicitly exclude .env files, credentials, private keys, dependency caches, and other unwanted local content. Raw --upload and files put --exclude have their own file-transfer filters.
Git activation atomically replaces the destination directory. --remote-dir must therefore name a replaceable child on the workspace filesystem, such as /workspace/repo or /workspace/alternate-repo, never the mounted /workspace root itself. Raw upload may target /workspace because it does not use Git-directory activation.
Atomic activation and the workspace fence
Aient constructs and verifies a candidate before activating it as/workspace/repo. V3 is selected only from a closed, exactly attested capability, publishes one immutable full-snapshot or retained-delta candidate, and never falls back after selection. Activation replaces the live child on the same filesystem while holding the exclusive workspace fence; the /workspace mount point itself is not replaced.
sandbox exec, sandbox shell, and workspace reads hold the shared fence. A sync waits before activation rather than replacing the live tree under an admitted command. Direct file operations currently fail with a busy response instead of waiting.
Do not start a second workspace mutation while a sync is active. Wait for the real terminal prefix:
Synchronized N explicit path(s) ... line.
Partial transfer progress is not completion. If another program invokes the CLI, it must preserve the child process’s complete lifecycle result—including a running session handle, final exit status, and terminal output. Completion of an outer wrapper is not evidence that the CLI child has exited.
Workspace archive uploads treat --timeout as an inactivity budget. The budget resets while source bytes continue to flow and when the server begins its response, so a healthy large transfer may exceed five minutes in total. A stalled upload or response still fails with a deadline-classified error.
For a slow connection, increase the allowed inactivity gap:
--verbose prints safe request correlation and detailed progress; it does not print credentials.
An interrupted upload does not resume from its last reported byte. See transfer recovery for automatic retries and retained-operation recovery.
Experimental selected-file live sync
Aient CLI 0.11.23 adds two experimental modes for watching selected local files in an existing sandbox. Use them when you want to send source edits without publishing a complete Git workspace on every save. Start with a running sandbox whose workspace has already been synchronised. For--live-stream, use a compatible native V3 sandbox with an attested workspace and customer shell permission. Pass the actual remote worktree path, with existing parent directories for every selected file:
--live-path to select up to 128 existing regular files, each at most 32 MiB. Paths are relative to the local repository. The usual Git and explicit extra-file selection rules apply; Git control paths, credentials, symlink sources, and submodules are rejected.
The initial upload overwrites the selected remote files. Later saves replace each file atomically, including ordinary editor saves that replace the local file. Identical captured content is skipped. Each acknowledgement confirms that file’s byte count and SHA-256; it does not confirm application readiness or browser hot reload.
The stream holds a shared workspace fence, so full workspace activation and exclusive file uploads remain blocked until it shuts down. Press Ctrl-C to request shutdown. If the CLI prints termination UNVERIFIED, the remote helper and fence may still be active. Starting another watcher does not recover that session and overwrites the selected files again. The reported session and process IDs are diagnostic information, not permission to terminate a process.
To send selected files through the files API instead, replace --live-stream with --live. This mode requires an attested existing workspace and customer files permission. Both modes require explicit --remote-dir and --live-path; choose only one mode.
Live sync does not transfer Git metadata, protect concurrent edits, propagate deletions or renames, select newly created files, or transfer mode changes. It provides neither an atomic update across multiple files nor reconnect recovery. Errors stop the watcher. Ending the watcher leaves the sandbox running, subject to its existing lifetime limits.
Live sync through supervised execution
Aient CLI 0.11.26 adds an experimental exec transport for a compatible existing customer workspace. Start the watcher before starting a long-running application: setup needs an exclusive workspace fence. After setup, writes share the fence with ordinary application execution.--remote-dir to its actual worktree path. Each selected file must already exist remotely as a regular file with one hard link, with existing ordinary parent directories. This transport limits each captured file to 64 KiB and preserves the remote file mode. Unsupported runtimes and operator profiles reject this transport; there is no automatic transport fallback.
An exact path, byte count, SHA-256 acknowledgement, and successful command completion confirm each write. If the CLI reports write UNCONFIRMED, remote bytes may have changed. The watcher stops without retrying; inspect and reconcile the selected files before restarting. Each write command has a 30-second limit, and the sandbox’s existing expiry still applies.
The overwrite and recovery limits above also apply here: delivery does not confirm application readiness or browser hot reload. Use Agent checkout sync for a one-shot update to an Agent-owned checkout.
Recover an interrupted workspace publication
Aient CLI 0.11.28 automatically retries supported transient network failures and incomplete responses during workspace transfers. Use the existingsandbox sync, workspace-backed sandbox run, or sandbox exec --workspace command; no new flag is required.
Retries keep the originally captured files and obtain fresh authorisation for the same target and operation. Candidate uploads replay the captured archive. Numbered Git-cache uploads replay only the affected part, so a lost response does not restart the whole pack.
Retries are bounded. Cancellation and authorisation failures stop the transfer. Partially streamed downloads and other mutations are not automatically replayed after an ambiguous failure. Selected-file Agent sync and experimental live sync keep their existing recovery limits.
If the command exits after publication starts, the CLI retains the operation and its captured files. Inspect the recorded operation before starting a new publication:
workspace resume continues publication only; it does not run the original command.
For eligible native V3 Git-cache transfers in 0.11.22, repeating the original command can recover the retained operation even after you edit local files. Recovery uses the original captured files. Publish later edits in a subsequent sync after recovery completes.
Recovery, lease refresh, and cleanup remain tied to the original allocation and workspace. A replacement sandbox with the same name is rejected before mutation. Older retained Git-cache captures without an allocation UUID remain readable, but cannot be resumed with mutations; their saved bytes are preserved.
If you no longer want an uncommitted publication, discard it explicitly: