# Deep Agents CLI Configuration Options for Remote Sandboxing Environments Like Daytona

> Explore Deep Agents CLI configuration options for remote sandboxing with Daytona. Learn to use --sandbox --sandbox-id and --sandbox-setup flags for seamless integration.

- Repository: [LangChain/deepagents](https://github.com/langchain-ai/deepagents)
- Tags: how-to-guide
- Published: 2026-03-17

---

**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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/_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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/integrations/daytona.py) implements the standard interface: `get_or_create` and `delete`. The factory in [`sandbox_factory.py`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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

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

```

This command creates a new Daytona sandbox, executes [`daytona_init.sh`](https://github.com/langchain-ai/deepagents/blob/main/daytona_init.sh) inside it to install dependencies, and launches the **coder** agent in the remote environment.

### Attach to an Existing Sandbox

```bash
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

```python
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`](https://github.com/langchain-ai/deepagents/blob/main/main.py) through `ServerConfig` to [`sandbox_factory.py`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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.