---
title: "Sandbox in the CLI"
canonical: https://trickest.com/docs/developer-tools/cli/sandbox
description: "Platform-session command limits, plus browser and desktop controls that run inside a sandbox."
---

# Sandbox in the CLI

The `trickest sandbox` command family targets **platform sandbox sessions**. It is not a command-line wrapper around the standalone `@trickest/sandbox` package.

<Warning>
The sandbox commands do not fully match the platform API. Use the [Sandbox SDK](/docs/developer-tools/sandbox-sdk) for direct environment control.
</Warning>

## Current limitations

| Command | Compatibility issue |
| --- | --- |
| `sandbox start` | Does not send the owning workflow or agent-session context required by the API |
| `sandbox status` | Uses an incompatible route instead of the platform's context-based status endpoint |
| `sandbox exec`, `sandbox files`, `sandbox stop` | Do not reliably supply the execution session ID required for these operations |
| `sandbox logs` | Session log streaming is unsupported; `--follow` is not a working log stream |

An HTTP error from these commands is not proof that your token is invalid or that no sandbox exists. Changing credentials or repeatedly creating environments does not correct an incompatible client request.

## Command output

For detached command logs today, use the dedicated SDK's command handles as described in [Commands and output](/docs/developer-tools/sandbox-sdk/commands). Command logs are different from a platform session-wide log stream.

## Lifecycle

A platform session is associated with a workflow or agent session. Its execution session ID is required for commands, files, and disposal. A cold start can return before the machine is ready; a successful HTTP response alone does not establish readiness.

Closing a process, stopping a desktop, and disposing of a sandbox are different
operations. Do not use the incompatible `sandbox stop` command as a reliable
cleanup step. See [Platform SDK sandbox sessions](/docs/developer-tools/sdk/sandbox)
for the supported session lifecycle and retention contract.

## 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 <ref>` or `browser type <ref> "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 <ref>` 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._