> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-harris-1786029617-6b0a55e.mintlify.site/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>

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

Managed Deep Agents currently supports LangSmith sandboxes:

<CodeGroup>
  ```python sandbox/__init__.py theme={null}
  from managed_deepagents import sandboxes

  sandbox = sandboxes.langsmith(
      scope="thread",
      idle_ttl_seconds=600,
      default_timeout=600,
  )
  ```

  ```ts sandbox/index.ts theme={null}
  import { sandboxes } from "managed-deepagents";

  export const sandbox = sandboxes.langsmith({
    scope: "thread",
    idleTtlSeconds: 600,
    defaultTimeout: 600,
  });
  ```
</CodeGroup>

LangSmith uses its default sandbox template unless you set `template_name` or `snapshot_id` in Python, or `templateName` or `snapshotId` in TypeScript. Set only one 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 `idle_ttl_seconds` or `idleTtlSeconds` to control when an idle sandbox can be reclaimed. Use `default_timeout` or `defaultTimeout` to bound each command.

## How the agent use 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>