# How to run LangChain Deep Agents in a sandbox backend

Pass `backend=RuntimeSandbox(sbx)` to `create_deep_agent`, and its shell and file tools 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 your host, from $0.03125 an hour for 2 vCPU and 4 GiB while it plans.**
`RuntimeSandbox` implements Deep Agents' `BaseSandbox`, so the harness, its
planning, subagents and skills stay as they are. `deepagents` 0.7.19 was the
current PyPI release on 25 September 2026; the backend ran in the harness's own
loop with Deep Agents 0.7.18 on 23 September 2026.

## 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, so on this backend they land in
the sandbox too, where the code it 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.19 source and LangChain's sandboxes page, read on
25 September 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: 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, and a
  command that runs past its limit comes back with a note saying it was
  stopped. Set another default with `RuntimeSandbox(sbx, timeout_seconds=600)`.
- **Output** past 100,000 characters is cut from the front and flagged as
  truncated, so the end of a long build log reaches the model;
  `max_output_chars` changes the limit.
- **Files** anywhere in the machine can be read and written. Paths under
  `/workspace` go through Runtime's file API; paths elsewhere move through a
  staged copy there.
- **Errors** come back as Deep Agents expects them: `file_not_found`,
  `permission_denied`, `is_directory` or `invalid_path`.

## Long tasks: pause, resume, fork

Deep agents run for a long time and often 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 1 to 365 days, and the next command wakes it by itself.
To let two subagents try competing approaches from the same prepared state,
`sbx.fork(count=2)` 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 each
time.

## Keep keys and spending safe

- **The model key** is used by the harness in your process. The backend sends
  the 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_cost_micros` on `Sandbox.create` refuses a first
  lease that would cost more, and `on_lease_end="stop"` ends it at its time
  limit instead of pausing.
- **Cap the account.** A daily spending limit on the Runtime key fails a create,
  wake or extension past it with `spending_limit_reached`, charging nothing;
  a read-only key watches without spending
  ([read-only keys and daily limits](/docs/security#read-only-keys-and-daily-limits)).
- **Narrow egress.** `network={"internet": True, "allow": ["github.com", "pypi.org", "*.pythonhosted.org"]}`
  at create; 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): a placeholder in
  the sandbox, the real value added by the host on requests 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, and $0.0075 per reserved GiB-hour. With both CPUs busy,
2 vCPU and 4 GiB is $0.08 an hour; a paused sandbox pays only storage
([pricing](/docs/pricing)). New accounts get 50 free sandbox hours, no card.

For the simpler tool-calling agent, see [LangChain](/integrations/langchain);
for a graph of your own, see [LangGraph](/integrations/langgraph). Many agents
at once are covered in [a sandbox for coding agents](/use-cases/coding-agent-sandbox).

## Sources

Checked 25 September 2026.

- [Deep Agents sandboxes](https://docs.langchain.com/oss/python/deepagents/sandboxes):
  the provider sandbox list and the `execute` tool
- [deepagents 0.7.19 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 September 2026.