# How to run LangChain Deep Agents in a sandbox backend

Pass `backend=RuntimeSandbox(sbx)` to `create_deep_agent`. Its shell and file tools then all run in one Runtime microVM.

**With Runtime as the backend, a deep agent's `execute`, `ls`, `read_file`,
`write_file`, `edit_file`, `glob` and `grep` all act on a Firecracker microVM,
not on your host. While the agent plans, the sandbox costs $0.03125 an hour
for 2 vCPU and 4 GiB.** `RuntimeSandbox` implements Deep Agents' `BaseSandbox`,
so the harness, its planning, its subagents and its skills work as before.
`deepagents` 0.7.32 was the current PyPI release on 25 October 2026. On 23
September 2026, the backend ran in the harness's own loop with Deep Agents
0.7.18.

## Install

```bash no-run
pip install "withruntime[deepagents]" langchain-anthropic
npx withruntime login
```

The `deepagents` extra installs Deep Agents 0.7 or later beside the SDK. The
login approves this machine in a browser. Servers use `RUNTIME_API_KEY`.

## A deep agent on a Runtime backend

```python check
from deepagents import create_deep_agent
from withruntime import Sandbox
from withruntime.deepagents import RuntimeSandbox


def solve(task: str) -> str:
    with Sandbox.create(timeout_seconds=1800) as sbx:
        agent = create_deep_agent(model="anthropic:claude-sonnet-4-6", backend=RuntimeSandbox(sbx))
        result = agent.invoke({"messages": [{"role": "user", "content": task}]})
        return result["messages"][-1].content


print(solve("Clone https://github.com/pallets/click, run its tests, and summarise any failures."))
```

The harness writes its plan and notes as files. On this backend, those files
are written to the sandbox too, where the code the agent runs can read them.

## Which backend runs `execute`?

Deep Agents offers the `execute` tool only when the backend can run commands.
From the `deepagents` 0.7.32 source and LangChain's sandboxes page, read on
25 October 2026:

| Backend                      | Where tools act                     | What its authors say                                                                       |
| ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ |
| `StateBackend` (the default) | Files in the graph's state          | No shell; for a non-sandbox backend "the `execute` tool will return an error message"      |
| `FilesystemBackend`          | A directory on your machine         | File tools only                                                                            |
| `LocalShellBackend`          | Your machine, with a shell          | "NO sandboxing or isolation"; not for "production environments" or "untrusted code"        |
| Provider sandboxes           | The provider's cloud                | LangSmith, Daytona, E2B, Modal, Runloop, Vercel, AgentCore and NVIDIA OpenShell are listed |
| `RuntimeSandbox`             | A Runtime microVM your code created | Every tool, including `edit_file`, `glob` and `grep`, runs in the sandbox                  |

The source's own warning on `LocalShellBackend` names the risk. The agent can
read "any accessible file, including secrets (API keys, credentials, `.env`
files, SSH keys, etc.)". The sandbox backend removes that risk. Your host's
files are not in the microVM at all.

## How the backend behaves

- **Commands** run in the sandbox with a default limit of 1,800 seconds. A
  command that runs past its limit returns with a note that it was stopped. Set
  another default with `RuntimeSandbox(sbx, timeout_seconds=600)`.
- **Output** longer than 100,000 characters is cut from the front and marked as
  truncated. The end of a long build log still reaches the model.
  `max_output_chars` changes the limit.
- **Files** at any path in the machine can be read and written. Paths under
  `/workspace` go through Runtime's file API. Other paths move through a staged
  copy there.
- **Errors** are returned in the form Deep Agents expects: `file_not_found`,
  `permission_denied`, `is_directory` or `invalid_path`.

## Long tasks: pause, resume, fork

Deep agents often run for a long time and stop to wait for a person. The
sandbox can wait with them:

```python check
from deepagents import create_deep_agent
from withruntime import Sandbox
from withruntime.deepagents import RuntimeSandbox

sbx = Sandbox.create(timeout_seconds=3600, idle_pause_seconds=900)
agent = create_deep_agent(model="anthropic:claude-sonnet-4-6", backend=RuntimeSandbox(sbx))
agent.invoke({"messages": [{"role": "user", "content": "Set up the project and draft a migration plan."}]})
sbx.pause()  # files, memory and processes kept; compute billing stops

# Hours later, perhaps in another process:
again = Sandbox.connect(sbx.id)
agent = create_deep_agent(model="anthropic:claude-sonnet-4-6", backend=RuntimeSandbox(again))
agent.invoke({"messages": [{"role": "user", "content": "Apply step one of the plan and run the tests."}]})
again.stop()
```

A paused sandbox is kept while you have credit. The next command wakes it
automatically. To let two subagents try competing approaches from the same
prepared state, call `sbx.fork(count=2)`. It returns two running copies, with
memory included ([images, volumes and snapshots](/docs/python#images-volumes-and-snapshots)).
Start from a [custom image](/docs/images) to skip installing the toolchain on
every run.

## Keep keys and spending safe

- **The model key** is used by the harness in your process. The backend sends
  only sandbox commands and file contents, never credentials.
- **Approval before commands.** Deep Agents' `interrupt_on`, such as
  `interrupt_on={"execute": True}`, pauses the graph for a person before a
  shell command. The sandbox limits what an approved command can reach.
- **Cap the sandbox.** `max_total_cost_micros` on `Sandbox.create` stops the
  sandbox once it has cost that much in total. `on_lease_end="stop"` ends it at
  its time limit instead of pausing it.
- **Cap the account.** A daily spending limit on the Runtime key makes a create,
  wake or extension fail once it would pass the limit. The call fails with
  `spending_limit_reached` and charges nothing. A read-only key can monitor
  usage without spending
  ([read-only keys and daily limits](/docs/security#read-only-keys-and-daily-limits)).
- **Narrow egress.** Pass this at create: `network={"internet": True, "allow": ["github.com", "pypi.org", "*.pythonhosted.org"]}`.
  The host enforces it, so root in the sandbox cannot change it.
- **Tokens the agent's code needs**, such as a GitHub token for `git push`, go
  in as [secrets](/docs/security#secrets-sandboxes-never-see). The sandbox sees
  a placeholder. The host adds the real value to requests sent to the hosts you
  name.

## What it costs

Runtime bills the CPU the agent's commands use, at $0.025 per vCPU-hour with a
floor of 50 millicores. Reserved memory costs $0.0075 per GiB-hour. With both CPUs busy,
2 vCPU and 4 GiB cost $0.08 an hour. A paused sandbox is billed only for
storage ([pricing](/docs/pricing)). A new account gets 100 free hours of a 1 GB machine in its
first 30 days, with no card needed.

For a simpler tool-calling agent, see [LangChain](/integrations/langchain).
For a graph of your own, see [LangGraph](/integrations/langgraph). For many
agents at the same time, see [a sandbox for coding agents](/use-cases/coding-agent-sandbox).

## Sources

Checked 25 October 2026.

- [Deep Agents sandboxes](https://docs.langchain.com/oss/python/deepagents/sandboxes):
  the provider sandbox list and the `execute` tool
- [deepagents 0.7.32 on PyPI](https://pypi.org/project/deepagents/): the source
  of `create_deep_agent`, its `StateBackend` default and `interrupt_on`, and
  the `LocalShellBackend` security warning quoted above
- [LangChain quickstart](https://docs.langchain.com/oss/python/langchain/quickstart):
  the `claude-sonnet-4-6` model id

Facts on this page were checked on 25 October 2026.