---
title: "Platform SDK sandbox sessions"
canonical: https://trickest.com/docs/developer-tools/sdk/sandbox
description: "Workflow-linked sandbox sessions through @trickest/sdk, current compatibility limits, readiness, and disposal."
---

# Platform SDK sandbox sessions

**`client.sandbox`** belongs to **`@trickest/sdk`**. It controls sandbox sessions attached to platform workflows or agent conversations. This is different from the standalone **`@trickest/sandbox`** package and its `Sandbox.create()` API.

For a new integration that needs to create an execution environment, run commands, and collect files directly, use the [Sandbox SDK guide](/docs/developer-tools/sandbox-sdk).

<Warning>
  The `@trickest/sdk` sandbox client does not fully match
  the current platform session contract. Its creation return type and health
  lookup are affected. Awaiting `startSession()` does not guarantee that the
  environment is ready. Use the standalone Sandbox SDK for direct environment
  control.
</Warning>

## Session IDs and readiness

Session creation needs a workflow ID or an agent-session ID for a scratch environment. These identify the owning context; the returned **`sessionId`** identifies the execution session used by command and file operations. They are not interchangeable IDs.

The current platform API has two creation paths:

| Response | Meaning                                    | Next step                                                                       |
| -------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| HTTP 200 | The warm path has confirmed readiness      | Use the returned `sessionId` for commands and files                             |
| HTTP 202 | Provisioning has started in the background | Wait for readiness through status updates; do not immediately execute a command |

`GET /api/sandbox/status` uses `vaultId` and either `workflowId` or `agentSessionId` to look up lifecycle status. A passive status read does not start a new environment. The platform can also broadcast sandbox status updates.

The SDK's `session.id` example is not valid against a cold response containing `sessionId` and provisioning status. Likewise, `getHealth(session.id)` does not provide the current context-based readiness lookup. Handle provisioning failures and impose a timeout when waiting.

## Stop and durable state

Stopping a **platform sandbox session** disposes of its execution environment. The platform's durable workspace state lives in the workspace store; this is not a filesystem snapshot of the machine. Do not assume every installed dependency or arbitrary path will survive disposal.

This differs from `stop()` on a persistent standalone sandbox, which can retain
its working directory for `Sandbox.get()` to resume. It does not retain the
entire container filesystem. Neither path preserves running processes when the
machine stops. Download evidence that must survive disposal and stop sessions
in cleanup even when commands fail.

## Related

- [Sandbox SDK](/docs/developer-tools/sandbox-sdk): the direct environment API.
- [Agent sandboxes](/docs/using-the-app/ai-agent/sandboxes): files, commands, previews, and retention.
- [CLI sandbox compatibility](/docs/developer-tools/cli/sandbox): current command limitations.
- [Agent sessions](/docs/developer-tools/sdk/sessions): the agent conversation/session API.

---
_Markdown source of https://trickest.com/docs/developer-tools/sdk/sandbox._