> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Daytona Sandbox Tools

> Run shell commands, execute Python, and manage files inside isolated [Daytona](https://www.daytona.io/) sandboxes.

# Daytona Sandbox Tools

## Description

The Daytona sandbox tools give CrewAI agents access to isolated, ephemeral compute environments powered by [Daytona](https://www.daytona.io/). Three tools are available so you can give an agent exactly the capabilities it needs:

* **`DaytonaExecTool`** — run any shell command inside a sandbox.
* **`DaytonaPythonTool`** — execute a block of Python source code inside a sandbox.
* **`DaytonaFileTool`** — read, write, append, list, delete, and inspect files inside a sandbox.

All three tools share the same sandbox lifecycle controls, so you can mix and match them while keeping state in a single persistent sandbox.

## Installation

```shell theme={null}
uv add "crewai-tools[daytona]"
# or
pip install "crewai-tools[daytona]"
```

Set your API key:

```shell theme={null}
export DAYTONA_API_KEY="your-api-key"
```

`DAYTONA_API_URL` and `DAYTONA_TARGET` are also respected if set.

## Sandbox Lifecycle

All three tools inherit lifecycle controls from `DaytonaBaseTool`:

| Mode                    | How to enable                | Sandbox created                         | Sandbox deleted                                                |
| ----------------------- | ---------------------------- | --------------------------------------- | -------------------------------------------------------------- |
| **Ephemeral** (default) | `persistent=False` (default) | On every `_run` call                    | At the end of that same call                                   |
| **Persistent**          | `persistent=True`            | Lazily on first use                     | At process exit (via `atexit`), or manually via `tool.close()` |
| **Attach**              | `sandbox_id="<id>"`          | Never — attaches to an existing sandbox | Never — the tool will not delete a sandbox it did not create   |

Ephemeral mode is the safe default: nothing leaks if the agent forgets to clean up. Use persistent mode when you want filesystem state or installed packages to carry across multiple tool calls — this is typical when pairing `DaytonaFileTool` with `DaytonaExecTool`.

## Examples

### One-shot Python execution (ephemeral)

```python Code theme={null}
from crewai_tools import DaytonaPythonTool

tool = DaytonaPythonTool()
result = tool.run(code="print(sum(range(10)))")
print(result)
# {"exit_code": 0, "result": "45\n", "artifacts": None}
```

### Multi-step shell session (persistent)

```python Code theme={null}
from crewai_tools import DaytonaExecTool, DaytonaFileTool

exec_tool = DaytonaExecTool(persistent=True)
file_tool = DaytonaFileTool(persistent=True)

# Install a package, then write and run a script — all in the same sandbox
exec_tool.run(command="pip install httpx -q")
file_tool.run(action="write", path="/workspace/fetch.py", content="import httpx; print(httpx.get('https://httpbin.org/get').status_code)")
exec_tool.run(command="python /workspace/fetch.py")
```

<Note>
  Each tool instance maintains its own persistent sandbox. To share **one** sandbox across two tools, create the first tool, grab its sandbox id via `tool._persistent_sandbox.id`, and pass it to the second tool via `sandbox_id=...`.
</Note>

### Attach to an existing sandbox

```python Code theme={null}
from crewai_tools import DaytonaExecTool

tool = DaytonaExecTool(sandbox_id="my-long-lived-sandbox")
result = tool.run(command="ls /workspace")
```

### Custom sandbox parameters

Pass Daytona's `CreateSandboxFromSnapshotParams` kwargs via `create_params`:

```python Code theme={null}
from crewai_tools import DaytonaExecTool

tool = DaytonaExecTool(
    persistent=True,
    create_params={
        "language": "python",
        "env_vars": {"MY_FLAG": "1"},
        "labels": {"owner": "crewai-agent"},
    },
)
```

### Agent integration

```python Code theme={null}
from crewai import Agent, Task, Crew
from crewai_tools import DaytonaExecTool, DaytonaPythonTool, DaytonaFileTool

exec_tool = DaytonaExecTool(persistent=True)
python_tool = DaytonaPythonTool(persistent=True)
file_tool = DaytonaFileTool(persistent=True)

coder = Agent(
    role="Sandbox Engineer",
    goal="Write and run code in an isolated environment",
    backstory="An engineer who uses Daytona sandboxes to safely execute code and manage files.",
    tools=[exec_tool, python_tool, file_tool],
    verbose=True,
)

task = Task(
    description="Write a Python script that prints the first 10 Fibonacci numbers, save it to /workspace/fib.py, and run it.",
    expected_output="The first 10 Fibonacci numbers printed to stdout.",
    agent=coder,
)

crew = Crew(agents=[coder], tasks=[task])
result = crew.kickoff()
```

## Parameters

### Shared (`DaytonaBaseTool`)

All three tools accept these parameters at initialization:

| Parameter         | Type           | Default            | Description                                                                                          |
| ----------------- | -------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| `api_key`         | `str \| None`  | `$DAYTONA_API_KEY` | Daytona API key. Falls back to the `DAYTONA_API_KEY` env var.                                        |
| `api_url`         | `str \| None`  | `$DAYTONA_API_URL` | Daytona API URL override.                                                                            |
| `target`          | `str \| None`  | `$DAYTONA_TARGET`  | Daytona target region.                                                                               |
| `persistent`      | `bool`         | `False`            | Reuse one sandbox across all calls and delete it at process exit.                                    |
| `sandbox_id`      | `str \| None`  | `None`             | Attach to an existing sandbox by id or name.                                                         |
| `create_params`   | `dict \| None` | `None`             | Extra kwargs forwarded to `CreateSandboxFromSnapshotParams` (e.g. `language`, `env_vars`, `labels`). |
| `sandbox_timeout` | `float`        | `60.0`             | Timeout in seconds for sandbox create/delete operations.                                             |

### `DaytonaExecTool`

| Parameter | Type                     | Required | Description                                   |
| --------- | ------------------------ | -------- | --------------------------------------------- |
| `command` | `str`                    | ✓        | Shell command to execute.                     |
| `cwd`     | `str \| None`            |          | Working directory inside the sandbox.         |
| `env`     | `dict[str, str] \| None` |          | Extra environment variables for this command. |
| `timeout` | `int \| None`            |          | Maximum seconds to wait for the command.      |

### `DaytonaPythonTool`

| Parameter | Type                     | Required | Description                                          |
| --------- | ------------------------ | -------- | ---------------------------------------------------- |
| `code`    | `str`                    | ✓        | Python source code to execute.                       |
| `argv`    | `list[str] \| None`      |          | Argument vector forwarded via `CodeRunParams`.       |
| `env`     | `dict[str, str] \| None` |          | Environment variables forwarded via `CodeRunParams`. |
| `timeout` | `int \| None`            |          | Maximum seconds to wait for execution.               |

### `DaytonaFileTool`

| Parameter   | Type          | Required | Description                                                           |
| ----------- | ------------- | -------- | --------------------------------------------------------------------- |
| `action`    | `str`         | ✓        | One of: `read`, `write`, `append`, `list`, `delete`, `mkdir`, `info`. |
| `path`      | `str`         | ✓        | Absolute path inside the sandbox.                                     |
| `content`   | `str \| None` |          | Content to write or append. Required for `append`.                    |
| `binary`    | `bool`        |          | If `True`, `content` is base64 on write; returns base64 on read.      |
| `recursive` | `bool`        |          | For `delete`: remove directories recursively.                         |
| `mode`      | `str`         |          | For `mkdir`: octal permission string (default `"0755"`).              |

<Tip>
  For files larger than a few KB, create the file first with `action="write"` and empty content, then send the body via multiple `action="append"` calls of \~4 KB each to stay within tool-call payload limits.
</Tip>