> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# tool_daytona

A RocketRide tool node that gives an agent a shared, ephemeral Daytona sandbox for remote code, shell commands, and text-file operations.

## About Daytona

Daytona is the external sandbox service this node accesses through its Python SDK. This node creates an ephemeral sandbox and uses it for code execution, shell commands, and file transfer during a pipeline run.

## What it does

Use this node when an agent must execute generated code or commands outside the engine host and retain files or installed packages across related tool calls. It exposes tools only, with no pipeline lanes, and creates its sandbox only when a tool first needs it. Pick it over a local execution tool when remote sandbox isolation and an automatically cleaned-up session are required.

## As a tool

The registered prefix is `daytona`, so the agent sees four functions.

| Function | Description |
|---|---|
| `daytona.run_code` | Runs source code in the configured sandbox language. |
| `daytona.run_command` | Runs a shell command, optionally in a sandbox working directory. |
| `daytona.upload_file` | Creates or overwrites a UTF-8 text file in the sandbox. |
| `daytona.download_file` | Reads a text file from the sandbox. |

### `daytona.run_code`

`code` is required and must be a non-empty string. The function returns `exit_code`, captured `output`, and `truncated`. A Daytona SDK failure instead returns `error`, `exit_code: -1`, empty output, and `truncated: false`.

### `daytona.run_command`

`command` is required and non-empty; optional `cwd` must be a string and is passed as the sandbox working directory when non-blank. The result and failure shape match `run_code`. Use it to install dependencies, build, or invoke shell programs in the same sandbox session.

### `daytona.upload_file`

`path` and string `content` are required. The function encodes content as UTF-8, creates or overwrites the file, and returns `success` with `path`. A Daytona failure returns `success: false`, the requested path, and `error`.

### `daytona.download_file`

`path` is required and non-empty. Successful output has `content` and `truncated`; missing files and SDK failures return empty content, `truncated: false`, and `error`. Unlike the other stateful calls, this function does not create a replacement sandbox after an expiration because an empty replacement cannot recover the file.

## Configuration

Provide the API key, then keep the defaults unless a particular sandbox workload needs a different image, language, lifetime, or output budget.

### API URL, Target Region, and Snapshot

Leave **API URL** blank to let the SDK use its default endpoint; set it only for a different Daytona endpoint. Leave **Target Region** blank to use the organization's default target, or select a target for a specific region. **Snapshot** is also optional and is passed when creating the sandbox; use it when a known snapshot supplies the runtime state your workload requires.

### Language

This sets the sandbox language used by `run_code` and defaults to `python`. The supported configured values are `python`, `javascript`, and `typescript`. `run_command` remains the tool for shell commands regardless of this setting.

### Auto-stop (minutes)

The shared sandbox is created as ephemeral, and this interval defaults to 5 minutes. After inactivity, server-side auto-stop deletes it; use a longer value only when calls need a longer idle gap without losing their files and installed packages. The node clamps configuration from 1 through 120 minutes, never allowing zero to disable this cost-safety cleanup.

### Execution Timeout (seconds) and Max Output (characters)

Both `run_code` and `run_command` use **Execution Timeout**, which defaults to 120 seconds and is clamped from 1 through 1,200. **Max Output** defaults to 50,000 characters and is clamped from 1,000 through 1,000,000; longer command output and downloaded file content are returned only up to that cap with `truncated: true`. Increase either only when the agent needs it, because timeout limits wait time and output limits protect its context window.

## Authentication

Provide a Daytona API key in **API Key**. The node fails pipeline startup when the key is empty.

## Notes

### Session lifecycle

All calls in a pipeline share one lazily created sandbox. A lock prevents simultaneous tool calls from creating multiple sandboxes. `run_code`, `run_command`, and `upload_file` retry once on a fresh sandbox when the prior handle has expired; any state from the old sandbox is gone and must be restored. Pipeline shutdown attempts to delete the sandbox, while ephemeral auto-stop remains the cleanup fallback if deletion fails.

## Upstream docs

- [Daytona documentation](https://www.daytona.io/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_daytona.api_url` | `string` | **API URL**<br/>Daytona API endpoint. Leave empty for the default cloud (https://app.daytona.io/api); set for self-hosted Daytona. | `""` |
| `tool_daytona.apikey` | `string` | **API Key**<br/>Daytona API key (app.daytona.io → Keys). | `""` |
| `tool_daytona.auto_stop_minutes` | `integer` | **Auto-stop (minutes)**<br/>Sandbox stops (and, being ephemeral, deletes itself) after this many minutes of inactivity: the cost safety net if cleanup is missed. | `5` |
| `tool_daytona.exec_timeout_secs` | `integer` | **Execution Timeout (seconds)**<br/>Max seconds a single run_code/run_command call may take. | `120` |
| `tool_daytona.language` | `string` | **Language**<br/>Language runtime for run_code in the sandbox. | `"python"` |
| `tool_daytona.max_output_chars` | `integer` | **Max Output (characters)**<br/>Output longer than this is truncated before being returned to the agent. | `50000` |
| `tool_daytona.snapshot` | `string` | **Snapshot**<br/>Daytona snapshot to create the sandbox from. Leave empty for the default snapshot. | `""` |
| `tool_daytona.target` | `string` | **Target Region**<br/>Sandbox region, e.g. "us" or "eu". Leave empty for the organization default. | `""` |

## Dependencies

- `daytona` `==0.140.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_daytona)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->
