Skip to main content

​
Retained sandbox lifecycle

Retain a sandbox when you want to run several commands against one uploaded workspace. For an environment-bound customer sandbox:
The one-shot command prints the created sandbox name. In Aient CLI 0.10.0, that environment-bound sandbox can be reused through selector-bearing 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. sync, files, and shell cannot reopen it. Start a fresh run --keep to transfer changed workspace state.

​
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:
Repeat the original --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:
The CLI prints a stable execution ID to stderr before dispatch:
Keep the sandbox name and execution ID if you may need to inspect or reconnect to the live execution. 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 shell

Open a new interactive PTY shell in a sandbox without an environment binding:
Every invocation opens a new shell. Shell reattachment, history replay, and capability-bearing environment or repository flags are not available in 0.10.0, so 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:
This is a sandbox runtime log snapshot, not stored command stdout/stderr history. Repeat the original --environment selector for an environment-bound customer sandbox.

​
aient sandbox delete

Delete a sandbox:
Delete retained sandboxes when you are finished. A sandbox lease is not a substitute for explicit cleanup.