From c28d0575220ef0a0142124881cbcbff2c7d91d58 Mon Sep 17 00:00:00 2001 From: DoganK01 Date: Tue, 28 Apr 2026 11:49:44 +0300 Subject: [PATCH] doc: add sandbox configuration docs for daytona and e2b --- .../sandbox-configuration/daytona.mdx | 94 +++++++++++++++++++ .../sandbox-configuration/e2b.mdx | 89 ++++++++++++++++++ docs.json | 9 +- 3 files changed, 191 insertions(+), 1 deletion(-) create mode 100644 concepts/autonomous-agent/sandbox-configuration/daytona.mdx create mode 100644 concepts/autonomous-agent/sandbox-configuration/e2b.mdx diff --git a/concepts/autonomous-agent/sandbox-configuration/daytona.mdx b/concepts/autonomous-agent/sandbox-configuration/daytona.mdx new file mode 100644 index 0000000..5e0eb5e --- /dev/null +++ b/concepts/autonomous-agent/sandbox-configuration/daytona.mdx @@ -0,0 +1,94 @@ +--- +title: "Daytona" +description: "Run AutonomousAgent code execution in a secure Daytona cloud sandbox while keeping file edits local." +--- + +## Overview + +[Daytona](https://www.daytona.io) provides isolated cloud sandboxes for running code, shell commands, and git operations. Pairing **DaytonaTools** with **AutonomousAgent** gives you the best of both worlds: the agent edits files locally in your workspace, but every code or shell execution happens in a remote sandbox — so untrusted output never touches your machine. + +**Toolkit Class:** `DaytonaTools` + + +For the full toolkit reference (all 11 tools, every parameter, advanced options) see [DaytonaTools](/concepts/tools/sandbox-tools/daytona). + + +## Setup + +```bash +pip install daytona +export DAYTONA_API_KEY="your-api-key" +``` + +## Example with AutonomousAgent + +The recommended pattern: keep `enable_filesystem=True` so the agent uses Upsonic's local sandboxed filesystem tools, disable `enable_shell` so no shell runs locally, and pass `DaytonaTools()` so all code and commands execute remotely. + +```python +from upsonic import AutonomousAgent, Task +from upsonic.tools.custom_tools.daytona import DaytonaTools + +agent = AutonomousAgent( + model="anthropic/claude-sonnet-4-5", + workspace="/path/to/project", + enable_filesystem=True, # local: write_file, edit_file, read_file, ... + enable_shell=False, # disable local shell + tools=[DaytonaTools()], # remote: daytona_run_code, daytona_run_command, ... +) + +task = Task("Read main.py, run it in the sandbox, and fix any errors.") +agent.print_do(task) +``` + +| Capability | Where it runs | Tools | +|---|---|---| +| File write/edit/delete | Local workspace | `write_file`, `edit_file`, `delete_file` | +| File read/search | Local workspace | `read_file`, `list_files`, `grep_files` | +| Code execution | Remote Daytona sandbox | `daytona_run_code` (Python/TypeScript/JavaScript) | +| Shell commands | Remote Daytona sandbox | `daytona_run_command` | +| Package install | Remote Daytona sandbox | `daytona_install_packages` | +| Git operations | Remote Daytona sandbox | `daytona_git_clone` | + + +All Daytona tools are prefixed with `daytona_` to avoid name collisions with the AutonomousAgent's local filesystem tools. + + +## Custom Configuration + +Pass options into `DaytonaTools()` to tune sandbox lifetime, language defaults, env vars, or restrict what the agent can do: + +```python +from upsonic import AutonomousAgent, Task +from upsonic.tools.custom_tools.daytona import DaytonaTools + +tools = DaytonaTools( + auto_stop_interval=120, # auto-stop after 2 hours idle + sandbox_language="python", # default language + env_vars={"MY_API_KEY": "sk-..."}, # env vars in the sandbox + labels={"project": "demo"}, # metadata labels + exclude_tools=["daytona_shutdown_sandbox"], # don't let the agent kill the sandbox +) + +agent = AutonomousAgent( + model="anthropic/claude-sonnet-4-5", + workspace="/path/to/project", + enable_shell=False, + tools=[tools], +) + +agent.print_do(Task("Install pandas and matplotlib, then plot a sales chart.")) +``` + +## Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `api_key` | `str \| None` | env `DAYTONA_API_KEY` | Daytona API key. | +| `api_url` | `str \| None` | env `DAYTONA_API_URL` | Daytona API URL. | +| `target` | `str \| None` | env `DAYTONA_TARGET` | Sandbox deployment region. | +| `sandbox_id` | `str \| None` | `None` | Connect to an existing sandbox instead of creating one. | +| `sandbox_language` | `str` | `"python"` | Default language: `python`, `typescript`, or `javascript`. | +| `env_vars` | `dict \| None` | `None` | Environment variables for the sandbox. | +| `labels` | `dict` | `{}` | Metadata labels attached to the sandbox. | +| `auto_stop_interval` | `int` | `60` | Minutes of idle time before auto-stop. `0` disables. | +| `timeout` | `int` | `300` | Sandbox creation timeout (seconds). | diff --git a/concepts/autonomous-agent/sandbox-configuration/e2b.mdx b/concepts/autonomous-agent/sandbox-configuration/e2b.mdx new file mode 100644 index 0000000..7b6e80b --- /dev/null +++ b/concepts/autonomous-agent/sandbox-configuration/e2b.mdx @@ -0,0 +1,89 @@ +--- +title: "E2B" +description: "Run AutonomousAgent code execution in a secure E2B cloud sandbox while keeping file edits local." +--- + +## Overview + +[E2B](https://e2b.dev) provides isolated cloud sandboxes for running code, shell commands, and managing files. Pairing **E2BTools** with **AutonomousAgent** lets the agent edit files locally in your workspace while every code or shell execution happens in a remote sandbox — keeping untrusted output off your machine. Supports Python, JavaScript, Java, R, and Bash. + +**Toolkit Class:** `E2BTools` + + +For the full toolkit reference (all 10 tools, every parameter, advanced options) see [E2BTools](/concepts/tools/sandbox-tools/e2b). + + +## Setup + +```bash +uv pip install e2b-code-interpreter +export E2B_API_KEY="your-api-key" +``` + +## Example with AutonomousAgent + +The recommended pattern: keep `enable_filesystem=True` so the agent uses Upsonic's local sandboxed filesystem tools, disable `enable_shell` so no shell runs locally, and pass `E2BTools()` so all code and commands execute remotely. + +```python +from upsonic import AutonomousAgent, Task +from upsonic.tools.custom_tools.e2b import E2BTools + +agent = AutonomousAgent( + model="anthropic/claude-sonnet-4-5", + workspace="/path/to/project", + enable_filesystem=True, # local: write_file, edit_file, read_file, ... + enable_shell=False, # disable local shell + tools=[E2BTools()], # remote: e2b_run_code, e2b_run_command, ... +) + +task = Task("Read main.py, run it in the sandbox, and fix any errors.") +agent.print_do(task) +``` + +| Capability | Where it runs | Tools | +|---|---|---| +| File write/edit/delete | Local workspace | `write_file`, `edit_file`, `delete_file` | +| File read/search | Local workspace | `read_file`, `list_files`, `grep_files` | +| Code execution | Remote E2B sandbox | `e2b_run_code` (Python/JS/Java/R/Bash) | +| Shell commands | Remote E2B sandbox | `e2b_run_command` | +| Package install | Remote E2B sandbox | `e2b_install_packages` | +| File transfer | Local ↔ Remote sandbox | `e2b_upload_file`, `e2b_download_file` | + + +All E2B tools are prefixed with `e2b_` to avoid name collisions with the AutonomousAgent's local filesystem tools. + + +## Custom Configuration + +Pass options into `E2BTools()` to tune sandbox lifetime, env vars, or restrict what the agent can do: + +```python +from upsonic import AutonomousAgent, Task +from upsonic.tools.custom_tools.e2b import E2BTools + +tools = E2BTools( + timeout=600, # 10-minute sandbox lifetime + sandbox_options={ + "envs": {"MY_API_KEY": "sk-..."}, # env vars in the sandbox + "metadata": {"project": "demo"}, + }, + exclude_tools=["e2b_shutdown_sandbox"], # don't let the agent kill the sandbox +) + +agent = AutonomousAgent( + model="anthropic/claude-sonnet-4-5", + workspace="/path/to/project", + enable_shell=False, + tools=[tools], +) + +agent.print_do(Task("Install pandas and matplotlib, then plot a sales chart.")) +``` + +## Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `api_key` | `str \| None` | env `E2B_API_KEY` | E2B API key. | +| `timeout` | `int` | `300` | Sandbox lifetime in seconds. Max 86400 (Pro) / 3600 (Hobby). | +| `sandbox_options` | `dict \| None` | `None` | Extra options for `Sandbox.create()` (e.g. `template`, `envs`, `metadata`). | diff --git a/docs.json b/docs.json index 8b4f2e3..2251570 100644 --- a/docs.json +++ b/docs.json @@ -89,7 +89,14 @@ "pages": [ "concepts/autonomous-agent/creating-an-autonomous-agent", "concepts/autonomous-agent/running-an-autonomous-agent", - "concepts/autonomous-agent/agents-md" + "concepts/autonomous-agent/agents-md", + { + "group": "Sandbox Configuration", + "pages": [ + "concepts/autonomous-agent/sandbox-configuration/daytona", + "concepts/autonomous-agent/sandbox-configuration/e2b" + ] + } ], "collapsed": false },