--- title: "Sandbox in the CLI" canonical: https://trickest.com/docs/developer-tools/cli/sandbox description: "List persistent devices, select a conversation computer, manage snapshots, and run commands in the current sandbox." --- # Sandbox in the CLI ## Choose the context `trickest sandbox` manages platform computers and sandbox sessions. Use the product computer IDs returned by `inventory`; native runtime IDs are different. The standalone [Sandbox SDK](/docs/developer-tools/sandbox-sdk) has its own environment lifecycle. Run `trickest sandbox --help` to check which commands your installed CLI supports. Inventory and creation need platform authentication and space access. Device creation requires Enterprise access and space write permission; Android and snapshots also require compatible runtime capabilities. Inside an Agent environment, `TRICKEST_AGENT_SESSION` identifies the conversation. Commands that accept `--session` can target it explicitly from another authenticated shell. Session execution commands use the active workflow or Agent workspace context; see [Configuration & Context](/docs/developer-tools/cli/configuration). ## Inventory and conversation devices Replace the uppercase placeholders with IDs returned by your environment. ```bash trickest sandbox inventory --space SPACE_UUID trickest sandbox ls --session SESSION_UUID trickest sandbox attach COMPUTER_UUID --session SESSION_UUID trickest sandbox use COMPUTER_UUID --session SESSION_UUID trickest sandbox use home --session SESSION_UUID ``` `inventory` lists accessible persistent devices without starting them. Continue with `--cursor` when the response has `nextCursor`, even after an empty page. `ls` lists the conversation's attached computers. `attach` adds a device to the conversation without selecting it; `use` changes the target for subsequent work. Already-running work stays where it started. Create a device with a stable UUID for the request: ```bash trickest sandbox create "Report workspace" --space SPACE_UUID --kind linux --request-id REQUEST_UUID ``` Use `--kind android` for a supported Android device. `--session SESSION_UUID` also attaches the new device without selecting it. If creation is interrupted, reuse the same request ID, name, space, and options. If only attachment failed, retry `sandbox attach` with the created computer ID instead of creating a replacement. Associate a device with a workflow using `sandbox associate COMPUTER_UUID WORKFLOW_UUID --session SESSION_UUID`, or pass `none` as the workflow to detach it. Association does not move files, change the owning space, select the device, or change the editor's workflow. ## Start, inspect, and stop ```bash trickest sandbox start --computer COMPUTER_UUID trickest sandbox status trickest sandbox exec 'pwd' trickest sandbox files ls /app trickest sandbox files push ./report.txt /app/report.txt ``` `start --computer` and `stop --computer` target a persistent inventory device directly. Without `--computer`, lifecycle and execution commands resolve the current platform context. Starting a named inventory device alone does not select it for later `status`, `exec`, or file commands. A provisioning response is not readiness: check status before depending on files or command execution. `exec --timeout` is retained for compatibility but ignored; the server applies its own limit. `sandbox logs --follow` is still unsupported as a session-wide log stream. Inspect individual command output instead. Stop an inventory device with `sandbox stop --computer COMPUTER_UUID` when its work is finished. Saved files can persist, but Linux processes do not. A goal or unresolved work receipt can reserve the device; finish or end the goal and resolve cleanup before stopping it. ## Copy between devices ```bash trickest sandbox files copy report.txt report.txt --from home --to COMPUTER_UUID --session SESSION_UUID ``` This copies one workspace file, replaces the destination, and verifies its bytes without switching devices. Files must be at most 8 MiB. Paths can be workspace-relative or under `/app`, `/trickest/sandbox`, or `/home/project`; operating-system `/tmp` is outside the supported roots. `home` always means the conversation's Home computer. ## Save and restore snapshots ```bash trickest sandbox snapshot ls COMPUTER_UUID trickest sandbox snapshot save COMPUTER_UUID "Ready for review" --request-id REQUEST_UUID trickest sandbox snapshot status COMPUTER_UUID --request-id REQUEST_UUID ``` Snapshot storage must be available. Finish active work and close the Linux browser before saving. A save is confirmed only when its state is `ready`. After an uncertain response, check the original request; reconcile by repeating save with the same request ID and name. Use `snapshot ls --space SPACE_UUID` to find snapshots across a space, including snapshots whose original computer was deleted. Snapshot IDs identify saved archives; request IDs identify save attempts. | Task | Command | | --- | --- | | Rename | `trickest sandbox snapshot name COMPUTER_UUID SNAPSHOT_ID "New name"` | | Restore a stopped device | `trickest sandbox snapshot restore COMPUTER_UUID SNAPSHOT_ID` | | Stop and restore | `trickest sandbox snapshot restore COMPUTER_UUID SNAPSHOT_ID --stop` | | Delete an archive | `trickest sandbox snapshot rm COMPUTER_UUID SNAPSHOT_ID` | Restore replaces the device's current state. Linux snapshots keep files and the saved browser profile, not process memory or open applications. Android capture and restore require a compatible runtime. External websites and accounts are not rolled back. To create a copy, pass both `--from-computer COMPUTER_UUID` and `--from-snapshot SNAPSHOT_ID` to `sandbox create`. Use `--stop-source` when the saved login requires the source to stop before the copy starts. See [Device Snapshots](/docs/using-the-app/computers/managing-snapshots) for the in-app controls. ## Start an app preview `trickest sandbox preview start` starts the managed App preview and waits for its server on port 3000. `--timeout SECONDS` bounds that readiness wait. Inspect the reported result and the selected context before starting a second server. ## Browser controls inside a sandbox `trickest browser` controls Chromium in the environment where the command runs. It does not select a remote platform sandbox from your laptop. The environment must include Chromium; otherwise the command reports `BROWSER_MISSING`. ```bash trickest browser open https://example.com trickest browser snapshot --interactive trickest browser screenshot ./page.png trickest browser tabs ``` Snapshots give interactive elements refs such as `e12`. Use a ref from the current snapshot with `browser click ` or `browser type "text"`. Upload paths refer to files inside that environment. `browser close` stops Chromium and keeps its profile, including cookies. ## Desktop controls inside a sandbox `trickest desktop` controls a virtual desktop and GUI applications in the same environment. It requires the desktop-enabled sandbox image; installing the CLI alone does not provide a desktop. ```bash trickest desktop screenshot ./screen.png trickest desktop snapshot --interactive trickest desktop windows ``` Desktop refs use `dN`. `desktop click ` can target a current ref; `desktop click 400,300` uses screen coordinates. `desktop type "text"` types into the focused window, and `desktop key "ctrl+s"` sends a keyboard shortcut. Use `desktop read` for text on surfaces without an accessibility tree. `desktop stream` starts the viewer connection. `desktop down` stops the desktop and loses running application state; it is not a sandbox deletion command. A missing desktop or stream dependency requires a compatible environment, not repeated login attempts. See [Using the computer](/docs/using-the-app/agent/using-the-computer) for the in-app viewer and control modes. ## Related - [Sandbox SDK](/docs/developer-tools/sandbox-sdk): create, run, collect, and delete from TypeScript. - [Agent sandboxes](/docs/key-concepts/agent/sandboxes): what agents can do in the environment. - [Configuration & Context](/docs/developer-tools/cli/configuration): active platform context. --- _Markdown source of https://trickest.com/docs/developer-tools/cli/sandbox._