Skip to main content
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.

Install provider dependency

Each provider ships as an optional extra. Install one from within a session with /install, or from the shell with dcode --install:
Included by default when installing deepagents-code. No extra installation needed.
To install support for every sandbox provider at once, use the all-sandboxes extra: /install all-sandboxes in a session, or dcode --install all-sandboxes from the shell.

Set provider credentials

export LANGSMITH_API_KEY="your-key"

Run Deep Agents Code with a sandbox

dcode --sandbox langsmith

​
Sandbox flags and examples

FlagDescription
--sandbox TYPESandbox provider to use. Built-ins: langsmith, agentcore, modal, daytona, runloop, vercel (default: none). Third-party and config-declared providers are also accepted. Pass --sandbox with no value to use [sandboxes].default from your config
--sandbox-id IDReuse an existing sandbox by ID instead of creating a new one. Skips creation and cleanup. Only for providers that support reattaching by ID. Refer to your sandbox documentation for more
--sandbox-snapshot-name NAMEUse or create a sandbox snapshot. Supported by langsmith and runloop (and any third-party provider that advertises snapshot support). Cannot be combined with --sandbox-id
--sandbox-setup PATHPath to a setup script to run inside the sandbox upon creation
Each provider exposes a default working directory inside the sandbox. Setup scripts and execute commands run from this directory unless overridden:
ProviderWorking directory
LangSmith/root
Daytona/home/daytona
Modal/workspace
Runloop/home/user
Vercel/vercel/sandbox
AgentCore/tmp
Examples: 
# Create a new Daytona sandbox
dcode --sandbox daytona

# 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
Because --sandbox accepts an optional value, keep the bare form last on the command line. Otherwise a following argument (e.g. dcode --sandbox agents) is consumed as the flag’s value. Pass an explicit provider name to avoid ambiguity.

​
Pluggable providers

The six built-in providers above aren’t 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 — the curated set above, installed as deepagents-code 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 isn’t installed or declared, Deep Agents Code lists the available providers and explains how to install or configure the missing one.
To distribute a provider so users can run dcode --sandbox <name> after installing your package, implement a SandboxProvider subclass and register it under the deepagents_code.sandbox_providers entry-point group.Override the metadata property so Deep Agents Code can surface your working directory and capability flags without instantiating the provider:
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):
        ...
Implement get_or_create and delete; async callers are handled by the base class. Then register the entry point in your package’s pyproject.toml:
[project.entry-points."deepagents_code.sandbox_providers"]
acme = "acme_sandbox.provider:AcmeProvider"
If you omit the metadata property, a generic default (/workspace, no snapshot support) is used.

​
Config-declared providers

For an in-house or local provider you don’t 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
required
Fully-qualified provider class in module.path:ClassName format. Deep Agents Code imports and instantiates this class for the provider.
​
working_dir
string
optional
Default working directory inside the sandbox. Defaults to /workspace.
​
package
string
optional
Package name suggested in error messages when the provider’s dependencies are missing.
​
supports_sandbox_id
boolean
optional
Whether --sandbox-id reattach is allowed for this provider. Defaults to true.
​
supports_snapshot_name
boolean
optional
Whether --sandbox-snapshot-name is allowed for this provider. Defaults to false.
​
params
object
optional
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.
Setting class_path causes Deep Agents Code to import and run arbitrary Python from the named module—module-level code executes on import. This is the same trust model as the model class_path: you control your own machine and your own config file.

​
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.
setup.sh
#!/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.
Sandboxes isolate code execution, but agents remain vulnerable to prompt injection with untrusted inputs. Use human-in-the-loop approval, short-lived secrets, and trusted setup scripts only. See Security considerations for details.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.