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 --:
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.
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.
sandbox run is buffered. It is convenient for bounded commands, but it does not provide durable detach or output replay. For long commands whose live progress matters, retain a sandbox and use sandbox exec.aient sandbox sync
Synchronise exact local Git state into an existing sandbox without an environment binding:
/workspace/repo. In 0.7.0, sync cannot carry the environment and repository selectors needed to reopen an environment-bound customer sandbox created by run --keep. Start a fresh run --keep to transfer changed customer workspace state.
/ separators and support *, **, and ?.
Excludes filter only the explicit non-Git layer and are valid only when the same command has at least one --include. They cannot remove tracked Git state. This dependency applies to Git workspace synchronisation; 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. 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.
For a large snapshot, increase the request budget:
--verbose prints safe request correlation and detailed progress; it does not print credentials.