---
title: "Sandbox SDK for AI agents"
canonical: https://trickest.com/docs/developer-tools/sandbox-sdk
description: "Create Linux sandboxes, run commands, manage files, and expose app previews with @trickest/sandbox."
---

# Sandbox SDK for AI agents

Use **`@trickest/sandbox`** when your application needs to create and control a Linux execution environment. It provides files, commands, detached work, app URLs, and sandbox lifecycle operations.

The SDK uses native fetch, has no runtime dependencies, and supports Node 22 or newer in your calling application. The sandbox's `runtime` option selects its remote environment separately.

## Choose your SDK

| SDK                                                        | Use it for                                                   | Entry point                 |
| ---------------------------------------------------------- | ------------------------------------------------------------ | --------------------------- |
| [Trickest SDK](/docs/developer-tools/sdk), `@trickest/sdk` | Workflows, runs, agent conversations, and platform data      | `new TrickestClient()`      |
| Sandbox SDK, `@trickest/sandbox`                           | A standalone Linux environment for commands, files, and apps | `Sandbox.create({ token })` |

Standalone sandbox creation does not require a workflow ID. The two SDKs have separate clients and lifecycle methods. `client.sandbox` belongs to the Trickest SDK and controls workflow-linked platform sessions. See [Platform sessions](/docs/developer-tools/sdk/sandbox) in the Trickest SDK menu.

## Install and authenticate

```bash
npm install @trickest/sandbox
```

Keep your Trickest API token in your server environment and pass it explicitly to `Sandbox.create`, `Sandbox.get`, or `Sandbox.list`. The returned handle retains the token for subsequent operations. The SDK does **not** read `TRICKEST_TOKEN` automatically.

Keep the token out of browser code and sandbox files. Your account needs sandbox
access and available capacity. Handle authentication and provisioning errors in
your application.

## Configure the endpoint

By default, this SDK calls `https://api.trickest.io/sandbox`. Set
`TRICKEST_SANDBOX_URL` only when using a different sandbox API deployment.
This differs from the platform SDK's app origin and `/api/*` routes.

`TRICKEST_SANDBOX_PUBLIC_DOMAIN` and `TRICKEST_SANDBOX_PUBLIC_SCHEME` are
optional settings for constructing preview URLs locally. You can use
`getPortDomain()` without them; see [App previews](/docs/developer-tools/sandbox-sdk/app-previews).

The SDK accepts `teamId` and `projectId` for compatibility but ignores them.
They do not select an authorization scope. The token and server determine access.

## Create, run, collect, delete

Save this as `sandbox-example.ts`, set `TRICKEST_TOKEN` in your environment, and run it with a TypeScript-capable runtime such as Bun. It creates a sandbox and deletes it in `finally`, including when a command or file operation fails.

```typescript
import { Sandbox } from "@trickest/sandbox";

const token = process.env.TRICKEST_TOKEN;
if (!token) throw new Error("TRICKEST_TOKEN is required");

const sandbox = await Sandbox.create({ token, runtime: "node24" });
try {
  await sandbox.writeFile("probe.js", "console.log(process.version)");
  const result = await sandbox.runCommand("node", ["probe.js"]);
  if (result.exitCode !== 0) {
    throw new Error(`Probe failed: ${await result.stderr()}`);
  }

  await sandbox.writeFile("probe-report.txt", await result.stdout());
  const report = await sandbox.readFileToBuffer({ path: "probe-report.txt" });
  if (report === null) throw new Error("Probe report is missing");
  console.log(new TextDecoder().decode(report));
} finally {
  await sandbox.delete();
}
```

Run the example with `bun sandbox-example.ts`. It prints the runtime version returned by your sandbox.

Relative file paths and commands use `/trickest/sandbox` by default. `stdout()` and `stderr()` are asynchronous methods; `exitCode` is a property. A failed command can return a nonzero exit code without throwing, so check it before treating the output as successful.

## Explore the Sandbox SDK

- [Commands & output](/docs/developer-tools/sandbox-sdk/commands): run commands, follow detached logs, and handle timeouts.
- [Files](/docs/developer-tools/sandbox-sdk/files): read, write, and collect results.
- [Lifecycle](/docs/developer-tools/sandbox-sdk/lifecycle): stop, resume, and delete environments.
- [App previews](/docs/developer-tools/sandbox-sdk/app-previews): expose a running application through a preview URL.

For the agent experience and isolation boundary, read [Agent sandboxes](/docs/using-the-app/ai-agent/sandboxes).

For the architectural rationale, read [why each managed sandbox gets its own instance](/blog/why-every-sandbox-gets-its-own-cloud-instance).

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