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

# Add a sandbox to Managed Deep Agents

> Configure an isolated filesystem and shell for Managed Deep Agents.

Agents often want to write or execute code when doing their job.
A sandbox gives a Managed Deep Agent an isolated filesystem and shell for working with files, running code, and executing commands.

<Note>
  Managed Deep Agents is in **public [beta](/langsmith/release-stages)** and available on [LangSmith Cloud](/langsmith/cloud) in the US region only.
</Note>

## Project structure

Keep the agent entry point at the project root and the sandbox declaration under `sandbox/`:

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
my-agent/
  agent.ts
  sandbox/
    index.ts
```

## Configure a sandbox

`mda init` scaffolds a sandbox declaration. Managed Deep Agents enables the sandbox only while the `sandbox/` directory is present. Delete the directory to opt out, such as for an agent that only needs its prompt, memory, and tools.

Declare the sandbox with `define_sandbox` (Python) or `defineSandbox` (TypeScript). Managed Deep Agents uses [LangSmith Sandboxes](/langsmith/sandboxes) for this backend:

```ts sandbox/index.ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { defineSandbox } from "managed-deepagents";

export const sandbox = defineSandbox({
  scope: "thread",
  idleTtlSeconds: 600,
  defaultTimeout: 600,
});
```

LangSmith uses its default sandbox template unless you set a custom template or snapshot. Set only one creation source.

Use `templateName` or `snapshotId` to set the creation source.

## Choose a scope

| Scope              | Behavior                                                                              |
| ------------------ | ------------------------------------------------------------------------------------- |
| `thread` (default) | Creates one sandbox for each durable thread and reuses it across runs on that thread. |
| `agent`            | Shares one sandbox across threads handled by the agent process.                       |

<Warning>
  An agent-scoped sandbox lets threads read and modify the same files. Use it only for intentionally shared state.
</Warning>

Use `idleTtlSeconds` to control when an idle sandbox can be reclaimed. Use `defaultTimeout` to bound each command.

## How the agent uses the sandbox

The agent uses filesystem tools such as `ls`, `read_file`, `write_file`, `edit_file`, `glob`, and `grep`, and runs shell commands with `execute`. Use `instructions.md` to specify where the agent should work and what it must not modify.

## Sandbox lifecycle

Managed Deep Agents owns sandbox naming, reuse, recovery, and cleanup. Deleting the deployment with `mda delete` also deletes the managed sandboxes associated with it. For platform-level lifecycle details, see [Sandboxes](/langsmith/sandboxes).

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-sandboxes.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>