Skip to content

feat: improve Daytona sandbox tools #5740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
greysonlalonde merged 8 commits into from
May 8, 2026
Merged

feat: improve Daytona sandbox tools #5740

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
bddba44
feat: improve Daytona sandbox tools
mislavivanda May 7, 2026
c2cb9fb
Merge branch 'main' into feat/daytona-sandbox-improvements
greysonlalonde May 7, 2026
202d574
Merge branch 'main' into feat/daytona-sandbox-improvements
greysonlalonde May 7, 2026
bbe269d
Merge branch 'main' into feat/daytona-sandbox-improvements
lorenzejay May 7, 2026
f242646
fix: revert sdk bump to ~=0.140.0 to avoid otel conflict
mislavivanda May 8, 2026
40bb500
fix(daytona): satisfy mypy with explicit None checks in _run dispatch
mislavivanda May 8, 2026
af0a799
Merge branch 'main' into feat/daytona-sandbox-improvements
greysonlalonde May 8, 2026
d23b0b3
Merge branch 'main' into feat/daytona-sandbox-improvements
greysonlalonde May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 64 additions & 14 deletions docs/ar/tools/ai-ml/daytona.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The Daytona sandbox tools give CrewAI agents access to isolated, ephemeral compu

- **`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.
- **`DaytonaFileTool`** — read, write, append, list, delete, and inspect files inside a sandbox; also supports `move`, `find` (content grep), `search` (filename glob), `chmod` (permissions), `replace` (bulk find-and-replace), and `exists`.

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

Expand Down Expand Up @@ -55,25 +55,30 @@ 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}
# {"exit_code": 0, "result": "45\n", "artifacts": ExecutionArtifacts(stdout="45\n", charts=[])}
```

### Multi-step shell session (persistent)

```python Code
from crewai_tools import DaytonaExecTool, DaytonaFileTool

# Create the persistent sandbox via the first tool, then attach the second
# tool to it so both share state (installed packages, files, env vars).
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")
file_tool = DaytonaFileTool(sandbox_id=exec_tool.active_sandbox_id)

file_tool.run(
action="write",
path="workspace/script.py",
content="import httpx; print(f'httpx loaded, version {httpx.__version__}')",
)
exec_tool.run(command="python workspace/script.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=...`.
By default, each tool with `persistent=True` lazily creates its **own** sandbox on first use. The pattern above shares a single sandbox across multiple tools by reading the first tool's `active_sandbox_id` after a `.run()` call and passing it to the others via `sandbox_id=...`. With `persistent=False` (the default), every `.run()` call gets a fresh sandbox that's deleted at the end of that call.
</Note>

### Attach to an existing sandbox
Expand All @@ -82,7 +87,7 @@ Each tool instance maintains its own persistent sandbox. To share **one** sandbo
from crewai_tools import DaytonaExecTool

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

### Custom sandbox parameters
Expand All @@ -102,6 +107,41 @@ tool = DaytonaExecTool(
)
```

### Searching, moving, and modifying files

```python Code
from crewai_tools import DaytonaFileTool

file_tool = DaytonaFileTool(persistent=True)

# Find every TODO in the source tree (grep file contents recursively)
file_tool.run(action="find", path="workspace/src", pattern="TODO:")

# Find all Python files (glob match on filenames)
file_tool.run(action="search", path="workspace", pattern="*.py")

# Make a script executable
file_tool.run(action="chmod", path="workspace/run.sh", mode="755")

# Rename or move a file
file_tool.run(
action="move",
path="workspace/draft.md",
destination="workspace/final.md",
)

# Bulk find-and-replace across multiple files
file_tool.run(
action="replace",
paths=["workspace/src/a.py", "workspace/src/b.py"],
pattern="old_function",
replacement="new_function",
)

# Quick existence check before a destructive op
file_tool.run(action="exists", path="workspace/cache.db")
```

### Agent integration

```python Code
Expand All @@ -121,7 +161,7 @@ coder = Agent(
)

task = Task(
description="Write a Python script that prints the first 10 Fibonacci numbers, save it to /workspace/fib.py, and run it.",
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,
)
Expand Down Expand Up @@ -168,12 +208,22 @@ All three tools accept these parameters at initialization:

| 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`. |
| `action` | `str` | ✓ | One of: `read`, `write`, `append`, `list`, `delete`, `mkdir`, `info`, `exists`, `move`, `find`, `search`, `chmod`, `replace`. |
| `path` | `str \| None` | ✓ for all actions except `replace` | Absolute path inside the sandbox. |
| `content` | `str \| None` | ✓ for `append` | Content to write or 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"`). |
| `mode` | `str \| None` | | For `mkdir`: octal permissions for the new directory (defaults to `"0755"`). For `chmod`: octal permissions to apply to the target. |
| `destination` | `str \| None` | ✓ for `move` | Destination path for `move`. |
| `pattern` | `str \| None` | ✓ for `find`, `search`, `replace` | For `find`: substring matched against file CONTENTS. For `search`: glob matched against file NAMES (e.g. `*.py`). For `replace`: text to replace inside files. |
| `replacement` | `str \| None` | ✓ for `replace` | Replacement text for `pattern`. |
| `paths` | `list[str] \| None` | ✓ for `replace` | List of file paths in which to replace text. |
| `owner` | `str \| None` | | For `chmod`: new file owner. |
| `group` | `str \| None` | | For `chmod`: new file group. |

<Note>
For `chmod`, pass at least one of `mode`, `owner`, or `group` — any field left as `None` is left unchanged on the target.
</Note>

<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.
Expand Down
42 changes: 22 additions & 20 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,7 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
Expand Down Expand Up @@ -764,6 +765,7 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
Expand Down Expand Up @@ -1724,8 +1726,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -2205,8 +2207,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -2686,8 +2688,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -3167,8 +3169,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -3647,8 +3649,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -4126,8 +4128,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -4605,8 +4607,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -5084,8 +5086,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -5565,8 +5567,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down Expand Up @@ -6045,8 +6047,8 @@
"en/tools/ai-ml/langchaintool",
"en/tools/ai-ml/ragtool",
"en/tools/ai-ml/codeinterpretertool",
"en/tools/ai-ml/e2bsandboxtools",
"en/tools/ai-ml/daytona"
"en/tools/ai-ml/daytona",
"en/tools/ai-ml/e2bsandboxtools"
]
},
{
Expand Down
78 changes: 64 additions & 14 deletions docs/en/tools/ai-ml/daytona.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The Daytona sandbox tools give CrewAI agents access to isolated, ephemeral compu

- **`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.
- **`DaytonaFileTool`** — read, write, append, list, delete, and inspect files inside a sandbox; also supports `move`, `find` (content grep), `search` (filename glob), `chmod` (permissions), `replace` (bulk find-and-replace), and `exists`.

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

Expand Down Expand Up @@ -55,25 +55,30 @@ 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}
# {"exit_code": 0, "result": "45\n", "artifacts": ExecutionArtifacts(stdout="45\n", charts=[])}
```

### Multi-step shell session (persistent)

```python Code
from crewai_tools import DaytonaExecTool, DaytonaFileTool

# Create the persistent sandbox via the first tool, then attach the second
# tool to it so both share state (installed packages, files, env vars).
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")
file_tool = DaytonaFileTool(sandbox_id=exec_tool.active_sandbox_id)

file_tool.run(
action="write",
path="workspace/script.py",
content="import httpx; print(f'httpx loaded, version {httpx.__version__}')",
)
exec_tool.run(command="python workspace/script.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=...`.
By default, each tool with `persistent=True` lazily creates its **own** sandbox on first use. The pattern above shares a single sandbox across multiple tools by reading the first tool's `active_sandbox_id` after a `.run()` call and passing it to the others via `sandbox_id=...`. With `persistent=False` (the default), every `.run()` call gets a fresh sandbox that's deleted at the end of that call.
</Note>

### Attach to an existing sandbox
Expand All @@ -82,7 +87,7 @@ Each tool instance maintains its own persistent sandbox. To share **one** sandbo
from crewai_tools import DaytonaExecTool

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

### Custom sandbox parameters
Expand All @@ -102,6 +107,41 @@ tool = DaytonaExecTool(
)
```

### Searching, moving, and modifying files

```python Code
from crewai_tools import DaytonaFileTool

file_tool = DaytonaFileTool(persistent=True)

# Find every TODO in the source tree (grep file contents recursively)
file_tool.run(action="find", path="workspace/src", pattern="TODO:")

# Find all Python files (glob match on filenames)
file_tool.run(action="search", path="workspace", pattern="*.py")

# Make a script executable
file_tool.run(action="chmod", path="workspace/run.sh", mode="755")

# Rename or move a file
file_tool.run(
action="move",
path="workspace/draft.md",
destination="workspace/final.md",
)

# Bulk find-and-replace across multiple files
file_tool.run(
action="replace",
paths=["workspace/src/a.py", "workspace/src/b.py"],
pattern="old_function",
replacement="new_function",
)

# Quick existence check before a destructive op
file_tool.run(action="exists", path="workspace/cache.db")
```

### Agent integration

```python Code
Expand All @@ -121,7 +161,7 @@ coder = Agent(
)

task = Task(
description="Write a Python script that prints the first 10 Fibonacci numbers, save it to /workspace/fib.py, and run it.",
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,
)
Expand Down Expand Up @@ -168,12 +208,22 @@ All three tools accept these parameters at initialization:

| 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`. |
| `action` | `str` | ✓ | One of: `read`, `write`, `append`, `list`, `delete`, `mkdir`, `info`, `exists`, `move`, `find`, `search`, `chmod`, `replace`. |
| `path` | `str \| None` | ✓ for all actions except `replace` | Absolute path inside the sandbox. |
| `content` | `str \| None` | ✓ for `append` | Content to write or 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"`). |
| `mode` | `str \| None` | | For `mkdir`: octal permissions for the new directory (defaults to `"0755"`). For `chmod`: octal permissions to apply to the target. |
| `destination` | `str \| None` | ✓ for `move` | Destination path for `move`. |
| `pattern` | `str \| None` | ✓ for `find`, `search`, `replace` | For `find`: substring matched against file CONTENTS. For `search`: glob matched against file NAMES (e.g. `*.py`). For `replace`: text to replace inside files. |
| `replacement` | `str \| None` | ✓ for `replace` | Replacement text for `pattern`. |
| `paths` | `list[str] \| None` | ✓ for `replace` | List of file paths in which to replace text. |
| `owner` | `str \| None` | | For `chmod`: new file owner. |
| `group` | `str \| None` | | For `chmod`: new file group. |

<Note>
For `chmod`, pass at least one of `mode`, `owner`, or `group` — any field left as `None` is left unchanged on the target.
</Note>

<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.
Expand Down
Loading
Loading