---
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

The platform API accepts a workflow ID or an agent-session ID for a scratch environment. The SDK’s `startSession({ workflowId, vaultId? })` helper accepts only the workflow form. 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 |

The SDK does not currently provide a supported readiness helper for this cold-start path. The app's status polling and broadcasts are internal UI mechanisms. For integrations that require readiness checks, use the [Sandbox SDK](/docs/developer-tools/sandbox-sdk).

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

`stopSession(sessionId)` stops the platform sandbox and its running processes.
The platform can resume retained workspace files when the context needs a
sandbox again. Stopping is different from resetting: reset deletes the sandbox
and clears its durable workspace.

Retained workspace files are not a complete machine backup. Dependency and
build directories can be excluded from snapshots, and resumed files do not
mean previous commands are still running. Download results that need an
independent copy before stopping or resetting.

## Related

- [Sandbox SDK](/docs/developer-tools/sandbox-sdk): the direct environment API.
- [Agent sandboxes](/docs/key-concepts/agent/sandboxes): the Linux environment the Agent uses for files and commands.
- [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._