---
title: "Run LangChain Deep Agents in a Promigence sandbox"
description: "Use a Promigence sandbox as the backend for a LangChain Deep Agent, or as the sandbox provider for deepagents-code."
url: "https://www.promigence.ai/docs/guides/langchain"
site: "Promigence"
---

# Run LangChain Deep Agents in a Promigence sandbox

Use a Promigence sandbox as the backend for a LangChain Deep Agent, or as the sandbox provider for deepagents-code.

LangChain Deep Agents run their shell and file tools through a sandbox backend. The
`langchain-promigence` package gives you `PromigenceSandbox`, a backend you pass to
`create_deep_agent`, so the agent's commands and file edits happen in a Promigence sandbox.
Installing it also registers a `promigence` provider for `deepagents-code`, so `dcode` can use it with
no extra wiring.

## What you need

- A Promigence API key in `PROMIGENCE_API_KEY`.
- Python 3.11 or newer (3.12 for the `deepagents-code` provider).
- `deepagents` 0.7.15. The package pins `>=0.7.15,<0.8`. The `dcode` provider was tested with
  `deepagents-code` 0.1.71.

## Install

```bash
pip install langchain-promigence
pip install "langchain-promigence[code]"     # adds the deepagents-code provider
export PROMIGENCE_API_KEY=prom_api_...
export PROMIGENCE_SPEND_CAP=5
```

## A minimal example

```python
from deepagents import create_deep_agent
from langchain_promigence import PromigenceSandbox

sandbox = PromigenceSandbox.create(image="python:3.12-slim", working_dir="/workspace", spend_cap=1)
try:
    agent = create_deep_agent(model="anthropic:claude-sonnet-4-5", backend=sandbox)
    agent.invoke({"messages": [{"role": "user", "content": "run the tests and fix what fails"}]})
finally:
    sandbox.kill()
```

From async code, use `acreate` and `akill`. The synchronous `create` refuses to run inside an event
loop and says so:

```python
sandbox = await PromigenceSandbox.acreate(image="python:3.12-slim", spend_cap=1)
await agent.ainvoke(...)
await sandbox.akill()
```

For `deepagents-code`, pick the provider on the command line and name the image in
`PROMIGENCE_IMAGE`:

```bash
dcode --sandbox promigence
```

Or set it in `~/.deepagents/config.toml`. An entry there takes the place of the registered provider,
so it names the provider class as well:

```toml
[sandboxes.providers.promigence]
class_path = "langchain_promigence.provider:PromigenceSandboxProvider"

[sandboxes.providers.promigence.params]
image = "ghcr.io/your-org/dev@sha256:..."
spend_cap = 5
```

Name the environment with `image` or `snapshot`. A tag is pinned to its digest for you, and the
machine running the agent needs no Docker. The first use of an image builds a snapshot from it: a
saved, verified environment that each sandbox starts as a fresh copy of. That build is billed per
second while it runs, whether it verifies or not, up to $0.17 at the default small size
([quickstart](https://www.promigence.ai/docs/quickstart)), and the sandboxes that reuse the snapshot pay no further build
charge. `setup` and `verify` let you prepare and check that snapshot. Set `working_dir`, because the
adapter does not read it from the image.

## One sandbox per backend

Each `PromigenceSandbox` is one sandbox. Give each agent run its own backend and the runs never see
each other's files. `sandbox.id` is the id that `promigence sandbox shell <id>` and
`dcode --sandbox-id` accept, which is handy when you want to look inside while an agent works.

## Setting a spend cap

`spend_cap` is the most one sandbox may spend, in US dollars. It falls back to
`PROMIGENCE_SPEND_CAP`, then to your organization's default; with none, creation fails with a
configuration error. `timeout_sec` (3600 by default) bounds the sandbox's lifetime.

## Cleaning up

Call `sandbox.kill()` (or `await sandbox.akill()`) when the run is over, ideally in `finally`. The
sandbox also ends on its own at `timeout_sec`.

Environment failures stay separate from the agent's. A command that exits non-zero comes back in
`ExecuteResponse.exit_code`. A failure of the sandbox itself raises `PromigenceEnvironmentError`
with `failure_class` set to `env`; that failure is not billed and is not the task's fault. A broken
image raises it with `env_definition`.

## What is not supported yet

- Images without `/bin/sh`, `python3` and `grep`. The Deep Agents file tools are built on them, so
  distroless images cannot run the agent's file tools.
- Streaming output. `execute` returns once the command finishes.
- `deepagents-code` snapshot names. Name the environment with `image` or `snapshot` instead.
- A JavaScript package. The JS Deep Agents sandbox interface is different and needs its own work.

## Next

Read [the agent briefing](https://www.promigence.ai/agents) for what a sandbox gives an agent, or start with
[the quickstart](https://www.promigence.ai/docs/quickstart).