> ## 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.ts
  sandbox/
    index.ts
    setup.sh   # optional
```

For the full project layout, see [Project structure](/langsmith/javascript/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 `defineSandbox`:

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

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

| Option           | Default | Description                                                                                         |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `idleTtlSeconds` | `600`   | Seconds of inactivity before the sandbox and its contents are deleted. Deletion is not recoverable. |
| `defaultTimeout` | `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                                        |
| -------------- | ------------------------------------------ |
| `snapshotName` | LangSmith snapshot name. Tags are allowed. |
| `snapshotId`   | LangSmith snapshot id.                     |
| `dockerImage`  | Published Docker image.                    |

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

export const sandbox = defineSandbox({
  idleTtlSeconds: 600,
  dockerImage: "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 `passwordEnv`:

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

export const sandbox = defineSandbox({
  dockerImage: "ghcr.io/acme/agent-base:1",
  registry: {
    url: "ghcr.io",
    username: "octocat",
    passwordEnv: "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/javascript/deepagents/tools#built-in-harness-tools), [`read_file`](/oss/javascript/deepagents/tools#built-in-harness-tools), [`write_file`](/oss/javascript/deepagents/tools#built-in-harness-tools), [`edit_file`](/oss/javascript/deepagents/tools#built-in-harness-tools), [`delete`](/oss/javascript/deepagents/tools#built-in-harness-tools), [`glob`](/oss/javascript/deepagents/tools#built-in-harness-tools), and [`grep`](/oss/javascript/deepagents/tools#built-in-harness-tools), and runs shell commands with [`execute`](/oss/javascript/deepagents/tools#built-in-harness-tools). Use [instructions](/langsmith/javascript/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/javascript/managed-deep-agents-memory)             |
| Always-on behavior without a filesystem                       | [Instructions](/langsmith/javascript/managed-deep-agents-instructions) |

For more information, see [Project structure](/langsmith/javascript/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>