---
title: "Agent sandboxes"
canonical: https://trickest.com/docs/using-the-app/ai-agent/sandboxes
description: "How agents use a Linux workspace, long-running commands, retained files, and app previews."
---

# Agent sandboxes

A sandbox gives an agent a Linux environment to run code, install tools, create
files, and build apps. Files and tools remain available across steps while the
sandbox runs.

## Work in one environment

The agent can use a shell with Node and Python available, install dependencies, and read or write files as its work develops. For example, it can process a dataset, write a script to investigate the output, and build a report over the results.

Related agent tasks can share a sandbox. A new model call or subtask does not automatically create a separate isolation boundary. Files, installed tools, and other state in that environment are shared by the work using it.

Ask the agent to identify the files it created and the commands it ran. Inspect the output behind its conclusions, and copy results you need to retain into storage outside the sandbox.

## Follow long-running work

A build, analysis, or other command can run detached from the request that started it. You can follow its logs, wait for completion, or stop it. Detached work can continue after a browser connection closes while its sandbox remains running.

Command lifetime and file retention are different. Stopping the machine ends running processes. Returning to retained files does not mean the previous processes are still running.

## Open what the agent builds

The agent can run an app or report and expose a preview URL. Open the page to inspect the result. The application must be running and its route registered; possession of a URL does not guarantee a working preview.

A preview depends on its sandbox. Export a report or move an application to an appropriate hosting environment if it needs to remain available after the sandbox is disposed of.

## Know what survives

There are two integration paths with different lifecycle contracts:

| Path | Retention and cleanup |
| --- | --- |
| Agent/platform sessions | The platform manages the workspace capture/restore lifecycle. Stopping a platform sandbox session disposes of its execution environment; durable state comes from the workspace store, not a filesystem snapshot of the machine |
| Standalone Sandbox SDK | A persistent sandbox can retain its working directory through stop/resume while it remains available. Other filesystem paths are not covered. `delete()` retires it permanently |

Neither path promises process continuity through stopping the machine. Do not treat the sandbox as your only copy of important evidence. Package installations, generated files, and a saved workspace are not interchangeable durability guarantees.

## Understand the isolation boundary

In the managed fleet, each sandbox has its own EC2 instance and guest operating system. Other Trickest sandboxes do not share that guest kernel or container daemon. Related tasks inside one sandbox remain in the same trust domain.

Separate instances may share physical AWS hardware. Instance isolation does not make code trustworthy or protect a credential deliberately given to that code. Keep credential scope, network access, and the sensitivity of input files appropriate to the work.

Workflow execution machines are a separate concept: they run node jobs selected by the workflow execution engine. See [Machines & Fleet](/docs/key-concepts/machines-and-fleet). The workflow fleet's plan table does not describe standalone sandbox access.

## Choose an integration

- Use the [Sandbox SDK](/docs/developer-tools/sandbox-sdk) to create environments and control files, commands, previews, and lifecycle from your own TypeScript application.
- Use the [platform SDK sandbox service](/docs/developer-tools/sdk/sandbox) for sessions attached to platform workflows.
- Check the [CLI sandbox reference](/docs/developer-tools/cli/sandbox) for current client limitations before using its session commands in automation.

---
_Markdown source of https://trickest.com/docs/using-the-app/ai-agent/sandboxes._