Deep Agents CLI Configuration Options for Remote Sandboxing Environments Like Daytona

The Deep Agents CLI supports remote sandboxing via three core flags: --sandbox to select the provider (daytona, modal, runloop, or langsmith), --sandbox-id to attach to existing instances, and --sandbox-setup to run initialization scripts inside the remote environment.

The langchain-ai/deepagents repository provides a command-line interface that can offload code execution to remote sandboxes. These configuration options for integrating the CLI with remote sandboxing environments like Daytona enable secure, isolated tool execution while maintaining full traceability through LangSmith metadata.

CLI Flags for Remote Sandbox Configuration

The CLI exposes sandbox configuration through arguments defined in libs/cli/deepagents_cli/main.py. These flags control how the CLI connects to and initializes remote execution environments.

Selecting the Sandbox Provider with --sandbox

The --sandbox flag determines which remote provider manages the execution environment. Valid choices are enforced by argparse as ["none", "daytona", "modal", "runloop", "langsmith"].

When you specify --sandbox daytona, the value is stored in ServerConfig.sandbox_type and serialized into the subprocess environment as DA_SERVER_SANDBOX_TYPE. The "none" option (default) disables remote execution entirely, forcing local tool execution. According to the source in main.py (lines 73-80), this flag populates server_kwargs that the TUI forwards to the server process.

Attaching to Existing Sandboxes with --sandbox-id

Use --sandbox-id to reuse an already-running sandbox rather than creating a new one. This string value is captured in ServerConfig.sandbox_id and passed to the provider's get_or_create method.

In libs/cli/deepagents_cli/integrations/sandbox_factory.py, the create_sandbox function checks this parameter: if sandbox_id is provided, the factory returns a wrapper around the existing instance; if None, it provisions a fresh sandbox. This allows persistent development environments across multiple CLI invocations.

Running Setup Scripts with --sandbox-setup

The --sandbox-setup flag accepts a path to a script that executes inside the sandbox immediately after creation. Stored as ServerConfig.sandbox_setup, this path is processed by _run_sandbox_setup in the server process.

The script runs via bash -c with local environment variables expanded, enabling you to configure dependencies, environment variables, or repository clones before the agent begins execution. This occurs in libs/cli/deepagents_cli/integrations/sandbox_factory.py before the backend handle is passed to the agent.

Configuration Flow from CLI to Sandbox Execution

The configuration traverses three architectural layers from user input to active sandbox:

1. Argument Parsing – main.py captures args.sandbox, args.sandbox_id, and args.sandbox_setup from the command line.
2. Configuration Serialization – ServerConfig.from_cli_args in _server_config.py (lines 22-27) normalizes the values, converting "none" to None, and to_env() serializes them into environment variables (DA_SERVER_SANDBOX_TYPE, DA_SERVER_SANDBOX_ID, DA_SERVER_SANDBOX_SETUP).
3. Server Initialization – The server process reads these variables via ServerConfig.from_env() and passes them to run_textual_cli_async.
4. Provider Resolution – deepagents_cli/integrations/sandbox_factory.py maps the sandbox_type to a concrete provider via _get_provider, resolving "daytona" to DaytonaProvider.
5. Sandbox Creation – create_sandbox instantiates the provider and either creates a new sandbox or attaches to the specified sandbox_id.
6. Setup Execution – If sandbox_setup is provided, _run_sandbox_setup renders and executes the script inside the remote environment.
7. Metadata Tracking – The sandbox_type is injected into LangSmith trace metadata in textual_adapter.py (lines 300-307), enabling filtering by execution environment in the LangSmith UI.

Daytona-Specific Implementation Details

The Daytona integration implements the SandboxProvider protocol through a dedicated provider class and backend wrapper.

Provider Abstraction and Factory

DaytonaProvider in libs/cli/deepagents_cli/integrations/daytona.py implements the standard interface: get_or_create and delete. The factory in sandbox_factory.py (lines 63-71) maps the string "daytona" to this class via the _PROVIDER_TO_WORKING_DIR dictionary, which also defines the default working directory as /home/daytona. This path informs the agent where to resolve relative file paths inside the sandbox.

Backend Wrapper Protocol

DaytonaSandbox in libs/partners/daytona/langchain_daytona/sandbox.py adapts the Daytona SDK to the Deep Agents BaseSandbox protocol. This wrapper forwards methods like execute, write, read, download, and upload, translating CLI-level calls into Daytona SDK operations. When the CLI invokes backend.execute(), the wrapper routes the command to the remote sandbox and returns the result.

Practical Configuration Examples

Launch a Fresh Daytona Sandbox with Initialization

deepagents \
  --sandbox daytona \
  --sandbox-setup ./scripts/daytona_init.sh \
  -a coder

This command creates a new Daytona sandbox, executes daytona_init.sh inside it to install dependencies, and launches the coder agent in the remote environment.

Attach to an Existing Sandbox

deepagents \
  --sandbox daytona \
  --sandbox-id sb-abc123 \
  -a researcher

The CLI connects to the running sandbox sb-abc123 without creating or terminating the instance, preserving state across sessions.

Programmatic Sandbox Creation

from deepagents_cli.integrations.sandbox_factory import create_sandbox

# Attach to existing Daytona sandbox

with create_sandbox("daytona", sandbox_id="sb-xyz987") as backend:
    result = backend.execute("python -c 'print(\"hello from daytona\")'")
    print(result.output)

The context manager handles cleanup only for sandboxes created within the call. When sandbox_id is provided, the existing instance remains running after exit.

Summary

• The Deep Agents CLI provides three configuration flags (--sandbox, --sandbox-id, --sandbox-setup) to control remote sandboxing behavior.
• Configuration flows from main.py through ServerConfig to sandbox_factory.py, where provider-specific logic creates or attaches to sandboxes.
• Daytona integration uses DaytonaProvider and DaytonaSandbox to wrap the Daytona SDK, with a default working directory of /home/daytona.
• The sandbox_type is automatically added to LangSmith metadata for execution environment tracing.
• Use --sandbox-id to persist state across CLI sessions, and --sandbox-setup to automate environment initialization.

Frequently Asked Questions

How do I switch from local execution to Daytona sandboxing?

Pass --sandbox daytona when invoking the CLI. By default, the CLI uses --sandbox none, which forces local execution. Changing this flag routes all tool execution through the Daytona provider, while the rest of your agent configuration remains unchanged.

Can I reuse an existing Daytona sandbox across multiple CLI sessions?

Yes. Use the --sandbox-id flag with the unique identifier of your running sandbox (e.g., --sandbox-id sb-abc123). The CLI will attach to this instance via the provider's get_or_create method rather than provisioning a new environment, allowing you to maintain state between commands.

What happens if the sandbox setup script fails?

If the script specified by --sandbox-setup returns a non-zero exit code, the _run_sandbox_setup function raises an exception that halts the server initialization process. The CLI will not start the agent until the setup script completes successfully, ensuring the environment is properly configured before tool execution begins.

How is the sandbox type tracked in LangSmith traces?

The CLI automatically injects sandbox_type into the trace metadata during run_textual_cli_async. As implemented in textual_adapter.py (lines 300-307), this metadata allows you to filter and analyze runs in the LangSmith UI based on whether they executed locally or inside a specific remote sandbox like Daytona.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}