Retained sandbox lifecycle
Retain a sandbox when you want to run several commands against one uploaded workspace. For an environment-bound customer sandbox:name field in JSON). In Aient CLI 0.11.17, that environment-bound sandbox can be reused through selector-bearing sandbox sync, sandbox exec, and sandbox execution, found with environment-scoped list, inspected with environment-scoped status, wait, and logs, and removed by its owner with delete. Run sync to publish changed workspace state. A sessionId identifies the physical runtime and is not a command target. files and shell cannot reopen the sandbox.
aient sandbox list
List sandboxes visible to the selected profile:
--environment applies customer environment authorisation before listing. --json is useful for scripts.
aient sandbox create
Create a retained sandbox without running a command:
Metadata must never contain credentials or sensitive values. It cannot override server-owned organisation, actor, environment, or repository identity.
The default Git transport bootstrap uses only hosts selected by the current repository’s
origin, upstream, and root .gitmodules. It merges matching public host records into the guest and, for GitHub, configures the sandbox user to use scoped HTTPS repository authority for SSH-form URLs. It does not copy private keys, SSH configuration, agents, sockets, or credentials. Installation restrictions produce a warning without turning successful sandbox creation into a failure.
For customer work that needs an environment’s authorised development capabilities, prefer sandbox run --environment ... --keep or supply --environment on later exec and execution-observation operations.
aient sandbox status
Show the current state of a sandbox:
--environment selector for an environment-bound customer sandbox.
aient sandbox wait
Wait until a sandbox becomes ready:
The global
--timeout limits the wait.
Repeat the original --environment selector for an environment-bound customer sandbox.
aient sandbox exec
Run a supervised command in an existing sandbox:
Exact argv,
--shell, and --stdin are mutually exclusive command forms. Repository authority requires --environment.
sandbox exec performs bounded same-execution transport recovery. It never replays an execution that may already have started.
aient sandbox docker bootstrap
Start a tmpfs-backed Docker daemon in a retained sandbox when a workflow needs Docker across more than one supervised command:
/workspace/repo. On compatible servers, it keeps live workspace consistency, so the daemon remains usable while a workspace sync publishes a new revision. --timeout bounds the daemon lifetime; the sandbox’s retention policy still applies.
Use --reset only to replace an existing daemon. It erases Docker and containerd data before preparation. If the CLI finds a ready daemon without a known live-consistency contract, it reports docker ready and tells you to rerun with --reset or recreate the sandbox before relying on sync.
An incompatible server rejects bootstrap before changing Docker state. Keep the printed execution ID if bootstrap does not complete so you can inspect its terminal state instead of starting another daemon.
aient sandbox shell
Open a new interactive PTY shell in a sandbox without an environment binding:
shell cannot address an environment-bound customer sandbox. Use sandbox exec --environment ... for authorised non-interactive operations.
aient sandbox logs
Read a bounded recent log snapshot from a sandbox:
--environment selector for an environment-bound customer sandbox.