> ## Documentation Index > Fetch the complete documentation index at: https://docs.aient.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retained sandbox lifecycle > Create, find, wait for, enter, inspect, and delete retained Aient sandboxes. # Retained sandbox lifecycle Retain a sandbox when you want to run several commands against one uploaded workspace. For an environment-bound customer sandbox: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient sandbox run \ --name laptop-offload \ --keep \ --environment development \ --repository example/widget \ -- true aient sandbox list --environment development aient --timeout 15m sandbox exec laptop-offload \ --environment development \ --repository example/widget \ --workdir /workspace/repo -- pnpm test aient sandbox delete laptop-offload ``` The one-shot command prints the created sandbox name. In Aient CLI 0.7.0, that environment-bound sandbox can be reused only through selector-bearing `sandbox exec` and `sandbox execution`, found with environment-scoped `list`, and removed by its owner with `delete`. `sync`, `files`, `shell`, `status`, `wait`, and `logs` cannot reopen it. Start a fresh `run --keep` to transfer changed workspace state. ## `aient sandbox list` List sandboxes visible to the selected profile: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient sandbox list aient sandbox list --environment development aient sandbox list --json ``` `--environment` applies customer environment authorisation before listing. `--json` is useful for scripts. ## `aient sandbox create` Create a retained sandbox without running a command: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient sandbox create --name laptop-offload --lease-seconds 21600 ``` | Flag | Meaning | | ---------------------- | ---------------------------------------------------- | | `--name NAME` | Requested sandbox name. | | `--lease-seconds N` | Requested lease. Default `7200`. | | `--metadata KEY=VALUE` | Non-secret control-plane metadata entry. Repeatable. | | `--json` | Emit structured output. | Metadata must never contain credentials or sensitive values. It cannot override server-owned organisation, actor, environment, or repository identity. 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 without an environment binding: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient sandbox status laptop-offload aient sandbox status laptop-offload --json ``` In 0.7.0, `status` cannot address an environment-bound customer sandbox. ## `aient sandbox wait` Wait until a sandbox without an environment binding becomes ready: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient --timeout 10m sandbox wait laptop-offload ``` | Flag | Meaning | | -------------------------- | ----------------------------------------- | | `--poll-interval DURATION` | Status polling interval. Default `500ms`. | | `--json` | Emit structured output. | The global `--timeout` limits the wait. In 0.7.0, `wait` cannot address an environment-bound customer sandbox. ## `aient sandbox exec` Run a supervised command in an existing sandbox: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient --timeout 15m sandbox exec laptop-offload \ --environment development \ --repository example/widget \ --workdir /workspace/repo -- pnpm test ``` The CLI prints a stable execution ID to stderr before dispatch: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Execution: 12345678-1234-4123-8123-123456789abc ``` Keep the sandbox name and execution ID if you may need to inspect or reconnect to the live execution. | Flag | Meaning | | -------------------------- | -------------------------------------------------------------------- | | `--workdir ABSOLUTE_PATH` | Working directory. Default `/workspace`. | | `--env KEY=VALUE` | Non-secret environment value. Repeatable. | | `--environment SLUG_OR_ID` | Authorise use of customer development capabilities. | | `--repository OWNER/NAME` | Select verified repository authority for provider-capable execution. | | `--shell COMMAND` | Explicit shell command. | | `--stdin` | Read an explicit shell command from standard input. | 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: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient sandbox shell laptop-offload ``` Every invocation opens a new shell. Shell reattachment, history replay, and capability-bearing environment or repository flags are not available in 0.7.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 without an environment binding: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient sandbox logs laptop-offload aient sandbox logs laptop-offload --tail-lines 500 aient sandbox logs laptop-offload --json ``` This is a sandbox runtime log snapshot, not stored command stdout/stderr history. In 0.7.0, `logs` cannot address an environment-bound customer sandbox. ## `aient sandbox delete` Delete a sandbox: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} aient sandbox delete laptop-offload ``` Delete retained sandboxes when you are finished. A sandbox lease is not a substitute for explicit cleanup.