# LangChain Deep Agents

Use Sandbox0 as the sandbox backend for LangChain Deep Agents and Deep Agents Code.

LangChain Deep Agents can run shell commands and file tools through a pluggable sandbox backend. The Sandbox0 adapter implements that backend with a Sandbox0 sandbox from the `default` template.

<Callout variant="info">
Deep Agents Code owns the sandbox lifecycle when it creates the sandbox. Pass an existing `--sandbox-id` when your application or operator should own the lifecycle instead.
</Callout>

## Requirements

- Python 3.11 or later for the Deep Agents dependencies.
- `sandbox0[deepagents]` installed from the Sandbox0 Python SDK.
- A Sandbox0 API key in `SANDBOX0_TOKEN` or passed to the provider.
- Optional `SANDBOX0_BASE_URL` when you are not using the default Sandbox0 Cloud endpoint.
- The Sandbox0 `default` template. The adapter uses `/workspace` as the Deep Agents working directory.

```bash
pip install "sandbox0[deepagents]"
```

The reviewed SDK extra pins `deepagents==0.7.0a2` and
`deepagents-code==0.1.26`; the Deep Agents dependency is a prerelease. Use a
compatible SDK release and keep those pins when reproducing this guide.
Configure Deep Agents' model provider and its authentication separately:
the Sandbox0 key authenticates sandbox operations, not model inference.

## Basic Usage

The package registers a Deep Agents Code sandbox provider named `sandbox0`.

```bash
export SANDBOX0_TOKEN=...
dcode --sandbox sandbox0
```

Deep Agents Code starts a Sandbox0 sandbox, gives the agent shell and file access through the Deep Agents sandbox backend, and deletes the sandbox when the Deep Agents Code session exits normally.

To set the Sandbox0 Cloud API endpoint explicitly:

```bash
export SANDBOX0_TOKEN=...
export SANDBOX0_BASE_URL=https://api.sandbox0.ai
dcode --sandbox sandbox0
```

## Sandbox Lifecycle

There are two ownership modes.

| Mode | How to start | Who deletes the sandbox | Use when |
|------|--------------|-------------------------|----------|
| Deep Agents Code-owned | `dcode --sandbox sandbox0` | Deep Agents Code calls the Sandbox0 provider delete hook on exit. | You want a disposable workspace for one agent session. |
| Caller-owned | `dcode --sandbox sandbox0 --sandbox-id sb_abc123` | You delete or retain the sandbox through Sandbox0. | You want to inspect, reuse, pause, resume, snapshot, or delete the sandbox yourself. |

### Deep Agents Code-Owned Lifecycle

When no `--sandbox-id` is passed, Deep Agents Code calls `Sandbox0Provider.get_or_create(sandbox_id=None)`.

For a fresh Sandbox0 sandbox, the provider:

1. Claims a sandbox from the `default` template.
2. Sets the Deep Agents working directory to `/workspace`.
3. Returns a `Sandbox0DeepAgentsSandbox` backend.
4. Deletes the Sandbox0 sandbox when Deep Agents Code exits normally.

New Sandbox0 sandboxes created by this provider use these default lifecycle limits:

| Field | Default | Behavior |
|-------|---------|----------|
| `ttl` | `3600` seconds | Runtime soft TTL. Sandbox0 can pause the sandbox after one hour and release runtime compute while preserving sandbox identity and checkpointed rootfs state. |
| `hard_ttl` | `2592000` seconds | Hard lifetime cap. Sandbox0 deletes the sandbox identity and durable rootfs state after 30 days. |

Normal cleanup attempts to delete the sandbox, but these limits also apply
during a long-running session. The soft TTL is a deadline from claim or an
explicit refresh, not idle detection. This provider does not automatically
refresh it or enable `auto_resume`. Configure a suitable TTL, explicitly
refresh it through Sandbox0, or use `0` to disable it. Hard TTL expiry can
delete state even if the agent is still in use. Interrupted clients and setup
failures can leave sandboxes behind; retain their IDs for explicit cleanup.

### Caller-Owned Lifecycle

Pass an existing Sandbox0 sandbox ID when the sandbox should survive the Deep Agents Code process:

```bash
dcode --sandbox sandbox0 --sandbox-id sb_abc123
```

In this mode, the provider reattaches to the existing sandbox and Deep Agents Code does not delete it on exit. The sandbox keeps whatever `ttl`, `hard_ttl`, network policy, services, and rootfs state it already has.
Reattachment only fetches metadata and returns a handle; it does not explicitly
resume a paused sandbox. Resume it before running shell tools, or configure
Sandbox0 `auto_resume` for supported runtime requests. Offline RootFS reads
and filesystem-only paused writes follow the normal Files API rules.

Use Sandbox0 APIs or `s0` to pause, resume, snapshot, fork, or delete the sandbox later.

## Override Lifecycle Defaults

For `dcode`, use `~/.deepagents/config.toml` when you need provider parameters that are not exposed as CLI flags.

Because Deep Agents config providers override entry-point discovery, include the provider class path when declaring `sandbox0` explicitly:

```toml
[sandboxes]
default = "sandbox0"

[sandboxes.providers.sandbox0]
class_path = "sandbox0_deepagents.provider:Sandbox0Provider"
working_dir = "/workspace"
package = "sandbox0[deepagents]"
supports_sandbox_id = true

[sandboxes.providers.sandbox0.params]
template = "default"
sandbox_ttl_sec = 7200
sandbox_hard_ttl_sec = 604800
```

This example creates new sandboxes with a two-hour soft TTL and seven-day hard TTL.

If you pass a full `SandboxConfig` programmatically, existing TTL values are
preserved when the corresponding `sandbox_ttl_sec` or `sandbox_hard_ttl_sec`
argument is omitted. Providing either argument explicitly overrides that field;
otherwise the provider fills missing lifecycle fields with its defaults.

## Python Backend Usage

Use `Sandbox0DeepAgentsSandbox` directly when your application creates and deletes the Sandbox0 sandbox itself.

```python
import os

from sandbox0 import Client
from sandbox0_deepagents import Sandbox0DeepAgentsSandbox


client = Client(
    token=os.environ["SANDBOX0_TOKEN"],
    base_url=os.environ.get("SANDBOX0_BASE_URL", "https://api.sandbox0.ai"),
)
sandbox = client.sandboxes.claim("default")
backend = Sandbox0DeepAgentsSandbox(sandbox=sandbox)

try:
    result = backend.execute("python3 - <<'PY'\nprint('hello from Sandbox0')\nPY")
    print(result.output)
finally:
    client.sandboxes.delete(sandbox.id)
```

In this mode, the backend does not own the sandbox lifecycle. Your application decides when to pause, resume, snapshot, fork, or delete the sandbox.

## File And Shell Semantics

The adapter inherits Deep Agents `BaseSandbox` behavior.

| Deep Agents operation | Sandbox0 path |
|-----------------------|---------------|
| `execute(...)` | Sandbox0 CMD context running `bash -lc` in `/workspace`. |
| `upload_files(...)` | Sandbox0 Files write API; also works during filesystem-only pause. |
| `download_files(...)` | Sandbox0 Files read API; also works during supported paused states. |
| `read`, `write`, `edit`, `ls`, `glob`, `grep`, `delete` | Deep Agents `BaseSandbox` helpers built from `execute`, `upload_files`, and `download_files`. |

Deep Agents file transfer APIs expect absolute sandbox paths. Relative upload or download paths return `invalid_path`.

The default Deep Agents working directory is `/workspace`, but file APIs can still access absolute paths that the sandbox process can access. Use Sandbox0 templates, rootfs layout, network policy, and credential boundaries to decide what should be reachable inside the sandbox.

## Production Guidance

- Use `dcode --sandbox sandbox0` for disposable agent sessions.
- Use `--sandbox-id` when an operator or application owns retention and cleanup.
- Create a named rootfs snapshot before deletion when the workspace must be reused, or export important files to an external system.
- Treat the default `ttl` and `hard_ttl` as safety limits, not as a substitute for explicit cleanup.
- Keep broad cloud credentials outside the sandbox. Prefer Sandbox0 network policy, protocol controls, credential sources, and egress auth for destination-scoped access.
- Use Sandbox0 pause, resume, snapshot, and fork APIs when you need to inspect or preserve an agent workspace.

## Next Steps

<CardGroup>
  <Card title="Pause And Resume" href="/docs/sandbox/pause-resume" cta="Continue">
    Understand `ttl`, `hard_ttl`, auto-resume, and runtime lifecycle behavior.
  </Card>

  <Card title="Files" href="/docs/sandbox/files" cta="Continue">
    Read, write, watch, and manage files inside a Sandbox0 sandbox.
  </Card>

  <Card title="OpenAI Agents" href="/docs/sandbox/integrations/openai-agents" cta="Continue">
    Compare the OpenAI Agents SDK integration and its rootfs snapshot lifecycle.
  </Card>
</CardGroup>