> ## Documentation Index
> Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Code execution sandbox

> Warm an isolated sandbox on each chat turn, run an AI SDK executeCode tool, and tear down right before the run suspends — using chat.agent hooks and chat.local.

<Warning>
  The AI Agents and Prompts surface ships as part of the **v4.5 release candidate**. Install with `@trigger.dev/sdk@rc` (or pin `4.5.0-rc.0` or later) to use these features — they aren't yet on the latest stable, and APIs may still change before the 4.5.0 GA. See [supported AI SDK versions](/ai-chat/reference#compatibility) and the [AI chat changelog](/ai-chat/changelog) for details.
</Warning>

Use a **hosted code sandbox** (for example [E2B](https://e2b.dev)) when the model should run short scripts to analyze tool output (PostHog queries, CSV-like data, math) without executing arbitrary code on the Trigger worker host.

This page describes a **durable chat** pattern that fits `chat.agent()`:

* **Warm** the sandbox at the start of each turn (**non-blocking**).
* **Reuse** it for every `executeCode` tool call during that turn (and across turns in the same run if you keep the handle).
* **Dispose** it **right before the run suspends** waiting for the next user message — using the **`onChatSuspend`** hook, not `onTurnComplete`.

## Why not tear down in `onTurnComplete`?

After a turn finishes, the chat runtime still goes through an **idle** window and only then suspends. During that window the run is still executing — useful for `chat.defer()` work — and the run hasn't suspended yet.

The boundary you want for “turn done, about to sleep” is **`onChatSuspend`**, which fires right before the run transitions from idle to suspended. It provides the `phase` (`”preload”` or `”turn”`) and full chat context. See [onChatSuspend / onChatResume](/ai-chat/lifecycle-hooks#onchatsuspend--onchatresume).

```mermaid theme={"theme":"css-variables"}
sequenceDiagram
  participant TurnStart as onTurnStart
  participant Run as run / streamText
  participant TurnDone as onTurnComplete
  participant Idle as Idle window
  participant Suspend as onChatSuspend
  participant Sleep as suspended

  TurnStart->>Run: warm sandbox (async)
  Run->>TurnDone: persist / inject / etc.
  TurnDone->>Idle: still running
  Idle->>Suspend: dispose sandbox
  Suspend->>Sleep: waiting for next message
```

## Recommended provider: E2B

* **API key** auth — works from any Trigger.dev worker; no Vercel-only OIDC.
* **Code Interpreter** SDK (`@e2b/code-interpreter`): long-lived sandbox, `runCode()`, `kill()`.

Alternatives (Modal, Daytona, raw Docker) are fine but more DIY. Vercel’s sandbox + AI SDK helpers are a better fit when execution stays **on Vercel**, not on the Trigger worker.

## Implementation sketch

### 1. Run-scoped sandbox map

Keep a `Map<runId, Promise<Sandbox>>` (or similar) in a **task-only module** so your Next.js app never imports it.

### 2. `onTurnStart` — warm without blocking

```ts theme={"theme":"css-variables"}
onTurnStart: async ({ runId, ctx, ...rest }) => {
  warmCodeSandbox(runId); // fire-and-forget Sandbox.create()
  // ...persist messages, writer, etc.
},
```

### 3. `chat.local` — run id for tools

Tool `execute` functions do not receive hook payloads. Use [`chat.local()`](/ai-chat/chat-local) to store the current run id for the sandbox key, **initialized from `onTurnStart`** (same `runId` as the map):

```ts theme={"theme":"css-variables"}
// In the same task module as your tools
import { chat } from "@trigger.dev/sdk/ai";

export const codeSandboxRun = chat.local<{ runId: string }>({ id: "codeSandboxRun" });

export function warmCodeSandbox(runId: string) {
  codeSandboxRun.init({ runId });
  // ...start Sandbox.create(), store promise in Map by runId
}
```

The **`executeCode`** tool reads `codeSandboxRun.runId` and awaits the sandbox promise before `runCode`.

### 4. `onChatSuspend` / `onComplete` — teardown

Use **`onChatSuspend`** to dispose the sandbox right before the run suspends, and **`onComplete`** as a safety net when the run ends entirely.

```ts theme={"theme":"css-variables"}
export const aiChat = chat.agent({
  id: "ai-chat",
  // ...
  onChatSuspend: async ({ phase, ctx }) => {
    await disposeCodeSandboxForRun(ctx.run.id);
  },
  onComplete: async ({ ctx }) => {
    await disposeCodeSandboxForRun(ctx.run.id);
  },
});
```

Unlike `onWait` (which fires for all wait types), `onChatSuspend` only fires at chat suspension points — no need to filter on `wait.type`. The `phase` discriminator tells you if this is a preload or post-turn suspension.

Optional **`onChatResume`**: log or reset flags; a fresh sandbox can be warmed again on the next **`onTurnStart`**.

### 5. AI SDK tool

Wrap the provider in a normal AI SDK `tool({ inputSchema, execute })` (same pattern as `webFetch`). Keep tool definitions in **task code**, not in the Next.js server bundle.

### 6. Environment

Set **`E2B_API_KEY`** (or your provider’s secret) on the **Trigger environment** for the worker — not in public client env.

## Typing `ctx`

Every `chat.agent` lifecycle event and the `run` payload include **`ctx`**: the same **[`TaskRunContext`](/ai-chat/reference#task-context-ctx)** shape as `task({ run: (payload, { ctx }) => ... })`.

```ts theme={"theme":"css-variables"}
import type { TaskRunContext } from "@trigger.dev/sdk";
```

The alias **`Context`** is also exported from `@trigger.dev/sdk` and is the same type.

## See also

* [Database persistence for chat](/ai-chat/patterns/database-persistence) — conversation + session rows, hooks, token renewal
* [Lifecycle hooks](/ai-chat/lifecycle-hooks)
* [API Reference — `ctx` on events](/ai-chat/reference#task-context-ctx)
* [Per-run data with `chat.local`](/ai-chat/chat-local)