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.

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.

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:

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 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#