From 13e0e9be6b30b03418dedf2c8a11f607beca6da9 Mon Sep 17 00:00:00 2001 From: Lorenze Jay <63378463+lorenzejay@users.noreply.github.com> Date: Tue, 28 Apr 2026 10:30:40 -0700 Subject: [PATCH] docs: add Daytona sandbox tools documentation (#5643) Adds docs for DaytonaExecTool, DaytonaPythonTool, and DaytonaFileTool introduced in PR #5530. Covers installation, lifecycle modes, examples, and full parameter reference. Registered in docs.json nav for all languages and versions. Co-authored-by: iris-clawd --- docs/ar/tools/ai-ml/daytona.mdx | 180 +++++++++++++++++++++++++++++ docs/docs.json | 132 ++++++++++++++------- docs/en/tools/ai-ml/daytona.mdx | 180 +++++++++++++++++++++++++++++ docs/ko/tools/ai-ml/daytona.mdx | 180 +++++++++++++++++++++++++++++ docs/pt-BR/tools/ai-ml/daytona.mdx | 180 +++++++++++++++++++++++++++++ 5 files changed, 808 insertions(+), 44 deletions(-) create mode 100644 docs/ar/tools/ai-ml/daytona.mdx create mode 100644 docs/en/tools/ai-ml/daytona.mdx create mode 100644 docs/ko/tools/ai-ml/daytona.mdx create mode 100644 docs/pt-BR/tools/ai-ml/daytona.mdx diff --git a/docs/ar/tools/ai-ml/daytona.mdx b/docs/ar/tools/ai-ml/daytona.mdx new file mode 100644 index 000000000..9447c6a3f --- /dev/null +++ b/docs/ar/tools/ai-ml/daytona.mdx @@ -0,0 +1,180 @@ +--- +title: Daytona Sandbox Tools +description: Run shell commands, execute Python, and manage files inside isolated [Daytona](https://www.daytona.io/) sandboxes. +icon: box +mode: "wide" +--- + +# 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 +uv add "crewai-tools[daytona]" +# or +pip install "crewai-tools[daytona]" +``` + +Set your API key: + +```shell +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=""` | 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 +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 +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") +``` + + +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=...`. + + +### Attach to an existing sandbox + +```python Code +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 +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 +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"`). | + + +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. + diff --git a/docs/docs.json b/docs/docs.json index e2e45df6e..cec8dec7b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -761,7 +761,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -1240,7 +1241,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -1719,7 +1721,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -2198,7 +2201,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -2677,7 +2681,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -3155,7 +3160,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -3632,7 +3638,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -4109,7 +4116,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -4586,7 +4594,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -5065,7 +5074,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -5543,7 +5553,8 @@ "en/tools/ai-ml/llamaindextool", "en/tools/ai-ml/langchaintool", "en/tools/ai-ml/ragtool", - "en/tools/ai-ml/codeinterpretertool" + "en/tools/ai-ml/codeinterpretertool", + "en/tools/ai-ml/daytona" ] }, { @@ -6039,7 +6050,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -6957,7 +6969,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -7416,7 +7429,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -7875,7 +7889,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -8334,7 +8349,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -8792,7 +8808,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -9250,7 +9267,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -9708,7 +9726,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -10165,7 +10184,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -10622,7 +10642,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -11080,7 +11101,8 @@ "pt-BR/tools/ai-ml/llamaindextool", "pt-BR/tools/ai-ml/langchaintool", "pt-BR/tools/ai-ml/ragtool", - "pt-BR/tools/ai-ml/codeinterpretertool" + "pt-BR/tools/ai-ml/codeinterpretertool", + "pt-BR/tools/ai-ml/daytona" ] }, { @@ -12052,7 +12074,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -12524,7 +12547,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -12996,7 +13020,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -13468,7 +13493,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -13940,7 +13966,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -14411,7 +14438,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -14882,7 +14910,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -15353,7 +15382,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -15823,7 +15853,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -16293,7 +16324,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -16764,7 +16796,8 @@ "ko/tools/ai-ml/llamaindextool", "ko/tools/ai-ml/langchaintool", "ko/tools/ai-ml/ragtool", - "ko/tools/ai-ml/codeinterpretertool" + "ko/tools/ai-ml/codeinterpretertool", + "ko/tools/ai-ml/daytona" ] }, { @@ -17737,7 +17770,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -18209,7 +18243,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -18681,7 +18716,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -19153,7 +19189,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -19625,7 +19662,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -20096,7 +20134,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -20567,7 +20606,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -21038,7 +21078,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -21508,7 +21549,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -21978,7 +22020,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { @@ -22449,7 +22492,8 @@ "ar/tools/ai-ml/llamaindextool", "ar/tools/ai-ml/langchaintool", "ar/tools/ai-ml/ragtool", - "ar/tools/ai-ml/codeinterpretertool" + "ar/tools/ai-ml/codeinterpretertool", + "ar/tools/ai-ml/daytona" ] }, { diff --git a/docs/en/tools/ai-ml/daytona.mdx b/docs/en/tools/ai-ml/daytona.mdx new file mode 100644 index 000000000..9447c6a3f --- /dev/null +++ b/docs/en/tools/ai-ml/daytona.mdx @@ -0,0 +1,180 @@ +--- +title: Daytona Sandbox Tools +description: Run shell commands, execute Python, and manage files inside isolated [Daytona](https://www.daytona.io/) sandboxes. +icon: box +mode: "wide" +--- + +# 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 +uv add "crewai-tools[daytona]" +# or +pip install "crewai-tools[daytona]" +``` + +Set your API key: + +```shell +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=""` | 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 +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 +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") +``` + + +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=...`. + + +### Attach to an existing sandbox + +```python Code +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 +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 +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"`). | + + +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. + diff --git a/docs/ko/tools/ai-ml/daytona.mdx b/docs/ko/tools/ai-ml/daytona.mdx new file mode 100644 index 000000000..9447c6a3f --- /dev/null +++ b/docs/ko/tools/ai-ml/daytona.mdx @@ -0,0 +1,180 @@ +--- +title: Daytona Sandbox Tools +description: Run shell commands, execute Python, and manage files inside isolated [Daytona](https://www.daytona.io/) sandboxes. +icon: box +mode: "wide" +--- + +# 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 +uv add "crewai-tools[daytona]" +# or +pip install "crewai-tools[daytona]" +``` + +Set your API key: + +```shell +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=""` | 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 +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 +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") +``` + + +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=...`. + + +### Attach to an existing sandbox + +```python Code +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 +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 +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"`). | + + +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. + diff --git a/docs/pt-BR/tools/ai-ml/daytona.mdx b/docs/pt-BR/tools/ai-ml/daytona.mdx new file mode 100644 index 000000000..9447c6a3f --- /dev/null +++ b/docs/pt-BR/tools/ai-ml/daytona.mdx @@ -0,0 +1,180 @@ +--- +title: Daytona Sandbox Tools +description: Run shell commands, execute Python, and manage files inside isolated [Daytona](https://www.daytona.io/) sandboxes. +icon: box +mode: "wide" +--- + +# 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 +uv add "crewai-tools[daytona]" +# or +pip install "crewai-tools[daytona]" +``` + +Set your API key: + +```shell +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=""` | 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 +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 +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") +``` + + +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=...`. + + +### Attach to an existing sandbox + +```python Code +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 +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 +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"`). | + + +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. +