> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-ramonn-1789138246-3410f5f.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 a managed deep agent.

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>

Put the sandbox declaration under `sandbox/`. Add `sandbox/setup.sh` only if you want to provision a snapshot:

```text theme={null}
my-agent/
  agent.py
  sandbox/
    __init__.py
    setup.sh   # optional
```

For the full project layout, see [Project structure](/langsmith/python/managed-deep-agents-project-structure).

## Configure a sandbox

Use a sandbox when the agent needs to write files, run code, or execute shell commands.

`mda init` scaffolds a sandbox declaration. Managed Deep Agents enables the sandbox only while the `sandbox/` directory is present.

`mda init` does not create `setup.sh`. Add that file yourself if the snapshot should install packages, clone a tree, or otherwise change the image.

Managed Deep Agents uses [LangSmith Sandboxes](/langsmith/sandboxes) for this backend. Reuse is always one sandbox per durable thread.

Declare the sandbox with `define_sandbox`:

```python sandbox/__init__.py theme={null}
from managed_deepagents import define_sandbox

sandbox = define_sandbox(
    idle_ttl_seconds=600,
    default_timeout=600,
)
```

| Option             | Default | Description                                                                                         |
| ------------------ | ------- | --------------------------------------------------------------------------------------------------- |
| `idle_ttl_seconds` | `600`   | Seconds of inactivity before the sandbox and its contents are deleted. Deletion is not recoverable. |
| `default_timeout`  | `600`   | Seconds allowed for each command.                                                                   |

## Provision a snapshot

If `sandbox/setup.sh` exists, `mda deploy` and `mda dev` run the script once and save the resulting environment as a snapshot. Modifications from that run, such as cloned repositories and installed packages, persist in the snapshot. New threads clone that snapshot instead of running `setup.sh`. The snapshot is reused until `setup.sh` changes, at which point it is rebuilt.

The script runs with `bash -e`. A non-zero exit fails the snapshot and the deploy or `mda dev` session. LangSmith does not update the live deployment to the failed snapshot. Any previously successful snapshot continues to serve.

```bash sandbox/setup.sh theme={null}
#!/usr/bin/env bash
set -euo pipefail

apt-get update && apt-get install -y jq
mkdir -p /workspace
```

Project `.env` values that deploy forwards are available as environment variables when `setup.sh` runs, for example a token used to clone a private repo. Thread sandboxes that clone the snapshot do not inherit those variables. Do not write secrets onto the filesystem while `setup.sh` runs; anything on disk is part of every thread's image.

Editing `setup.sh` and redeploying does not wipe `/workspace` on live threads. Those boxes keep the files they already have. A new thread clones the new snapshot.

## Choose a bake base

With no bake base, LangSmith's default sandbox template is the starting point. To start from something else, set exactly one of these:

| Option          | Use                                        |
| --------------- | ------------------------------------------ |
| `snapshot_name` | LangSmith snapshot name. Tags are allowed. |
| `snapshot_id`   | LangSmith snapshot id.                     |
| `docker_image`  | Published Docker image.                    |

```python sandbox/__init__.py theme={null}
from managed_deepagents import define_sandbox

sandbox = define_sandbox(
    idle_ttl_seconds=600,
    docker_image="python:3.12-slim",
)
```

For a private image, pass the image and a `registry`. Managed Deep Agents creates or updates a deployment-owned Host registry at bake time. Only the variable name is compiled; the credential value does not enter the build or the snapshot.

Name the password in `password_env`:

```python sandbox/__init__.py theme={null}
from managed_deepagents import define_sandbox

sandbox = define_sandbox(
    docker_image="ghcr.io/acme/agent-base:1",
    registry={
        "url": "ghcr.io",
        "username": "octocat",
        "password_env": "GHCR_TOKEN",
    },
)
```

Put `GHCR_TOKEN` in the project `.env` or the process environment. After bake, Managed Deep Agents does not forward that value to the running Agent Server.

## How the agent uses the sandbox

The agent uses built-in filesystem tools such as [`ls`](/oss/python/deepagents/tools#built-in-harness-tools), [`read_file`](/oss/python/deepagents/tools#built-in-harness-tools), [`write_file`](/oss/python/deepagents/tools#built-in-harness-tools), [`edit_file`](/oss/python/deepagents/tools#built-in-harness-tools), [`delete`](/oss/python/deepagents/tools#built-in-harness-tools), [`glob`](/oss/python/deepagents/tools#built-in-harness-tools), and [`grep`](/oss/python/deepagents/tools#built-in-harness-tools), and runs shell commands with [`execute`](/oss/python/deepagents/tools#built-in-harness-tools). Use [instructions](/langsmith/python/managed-deep-agents-instructions) to specify where the agent should work and what it must not modify.

## Disable the sandbox

Delete the `sandbox/` directory to opt out, such as for an agent that only needs its prompt, memory, and tools.

For existing deployments, deleting the deployment with `mda delete` also deletes the managed sandboxes associated with it, the `{deployment}--setup-*` recipe snapshots, and the deployment-owned registry when one exists.

## Deployment

Managed Deep Agents owns sandbox naming, recipe bake, reuse, recovery, and cleanup. Each durable thread gets its own sandbox, cloned from the current recipe snapshot. For platform-level lifecycle details, see [Sandboxes](/langsmith/sandboxes).

## When to use a sandbox

| Goal                                                          | Use                                                                |
| ------------------------------------------------------------- | ------------------------------------------------------------------ |
| Write files, run code, or execute shell commands in isolation | Sandbox                                                            |
| Store durable knowledge across threads                        | [Memory](/langsmith/python/managed-deep-agents-memory)             |
| Always-on behavior without a filesystem                       | [Instructions](/langsmith/python/managed-deep-agents-instructions) |

For more information, see [Project structure](/langsmith/python/managed-deep-agents-project-structure).

***

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