Use remote sandboxes

Deep Agents Code uses the sandbox as tool pattern: the dcode process (LLM loop, memory, tool dispatch) runs on your machine, but agent tool calls (read_file, write_file, execute, etc.) target the remote sandbox, not your local filesystem. To get files into the sandbox, use a setup script or the provider's file transfer APIs (see Working with files).

For a deeper look at sandbox architecture, integration patterns, and security best practices, see Sandboxes.

Sandbox flags and examples

Each provider exposes a default working directory inside the sandbox. Setup scripts and execute commands run from this directory unless overridden:

Examples:

# Create a new LangSmith sandbox
dcode --sandbox langsmith

# Boot from a named snapshot (langsmith, daytona, or runloop)
dcode --sandbox daytona --sandbox-snapshot-name my-env

# Reuse an existing sandbox (skips creation and cleanup)
dcode --sandbox runloop --sandbox-id dbx_abc123

# Run a setup script after sandbox creation
dcode --sandbox modal --sandbox-setup ./setup.sh

# Use the provider set as [sandboxes].default in config
dcode --sandbox

Pluggable providers

The built-in providers are not the only options. Deep Agents Code discovers sandbox providers from three sources, so you can use providers shipped by other packages or declare your own without changing Deep Agents Code:

1. Built-in providers — LangSmith, AgentCore, Daytona, Modal, Runloop, and Vercel, shipped with deepagents-code (LangSmith by default, the others as extras).
2. Third-party providers — published by other installed packages via a Python entry point.
3. Config-declared providers — defined in your ~/.deepagents/config.toml.

When two sources define the same provider name, config wins over third-party entry points, which win over built-ins, so your config file can always override discovery.

Third-party providers

A package can publish a sandbox provider under the deepagents_code.sandbox_providers entry-point group. Once you install such a package, its provider is available to --sandbox automatically—no config needed:

# Install the package that publishes the provider, then use it
dcode --sandbox acme

For example, the langchain-e2b package publishes an e2b provider (see sandbox integrations). Install it as a package, set your credentials, then select it:

dcode --install langchain-e2b --package
export E2B_API_KEY="..."
dcode --sandbox e2b

If you pass a --sandbox name that is not installed or declared, Deep Agents Code lists the available providers and explains how to install or configure the missing one.

from deepagents_code.integrations.sandbox_provider import (
    SandboxInstallHint,
    SandboxProvider,
    SandboxProviderMetadata,
)


class AcmeProvider(SandboxProvider):
    @property
    def metadata(self) -> SandboxProviderMetadata:
        return SandboxProviderMetadata(
            name="acme",
            working_dir="/workspace",
            install=SandboxInstallHint(kind="package", name="acme-dcode-sandbox"),
            supports_sandbox_id=True,
            supports_snapshot_name=False,
        )

    def get_or_create(self, *, sandbox_id=None, **kwargs):
        ...  # return a SandboxBackendProtocol

    def delete(self, *, sandbox_id, **kwargs):
        ...

[project.entry-points."deepagents_code.sandbox_providers"]
acme = "acme_sandbox.provider:AcmeProvider"

Config-declared providers

For an in-house or local provider you do not want to package, declare it under [sandboxes.providers] in ~/.deepagents/config.toml. This parallels arbitrary model providers and uses the same class_path trust model.

[sandboxes]
# Used when you run `dcode --sandbox` with no value.
default = "acme"

[sandboxes.providers.acme]
# Required: the provider class to import, in module.path:ClassName format.
class_path = "acme_sandbox.provider:AcmeProvider"
# Default working directory inside the sandbox.
working_dir = "/workspace"
# Package suggested when the provider's dependencies are missing.
package = "acme-dcode-sandbox"
# Capability flags (defaults: supports_sandbox_id = true, supports_snapshot_name = false).
supports_sandbox_id = true
supports_snapshot_name = false

# Extra keyword arguments forwarded to the provider's get_or_create().
[sandboxes.providers.acme.params]
region = "us-east-1"

class_path string

Fully-qualified provider class in module.path:ClassName format. Deep Agents Code imports and instantiates this class for the provider.

working_dir string

Default working directory inside the sandbox. Defaults to /workspace.

package string

Package name suggested in error messages when the provider's dependencies are missing.

supports_sandbox_id boolean

Whether --sandbox-id reattach is allowed for this provider. Defaults to true.

supports_snapshot_name boolean

Whether --sandbox-snapshot-name is allowed for this provider. Defaults to false.

params object

Extra keyword arguments forwarded to the provider's get_or_create().

A config entry that reuses a built-in provider's name overrides that built-in while keeping its dependency pre-flight check. Malformed entries are skipped with a warning rather than crashing startup.

Setup scripts

Use --sandbox-setup to run a shell script inside the sandbox after creation. This is useful for cloning repos, installing dependencies, and configuring environment variables.

#!/bin/bash
set -e

# Clone repository using GitHub token
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
cd $HOME/workspace

# Make environment variables persistent
cat >> ~/.bashrc <<'EOF'
export GITHUB_TOKEN="${GITHUB_TOKEN}"
export OPENAI_API_KEY="${OPENAI_API_KEY}"
cd $HOME/workspace
EOF
source ~/.bashrc

Deep Agents Code expands ${VAR} references in setup scripts using your local environment variables. Store secrets in a local .env file for the setup script to access.