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

# tool_python

A RocketRide tool node that lets an agent run small Python calculations or transformations when a built-in tool is not enough. Pick it for bounded code execution, not for integrations that need filesystem, network, or subprocess access.

## About RestrictedPython

RestrictedPython is a Python library for defining and enforcing a restricted execution environment. This node uses it to compile agent-supplied source with restricted guards and safe builtins.

## What it does

The node exposes one sandboxed execution tool and has no data lanes. It is suited to calculations, data reshaping, text processing, and other code that can run with the allowlisted imports; choose a purpose-built integration when the task needs an external system. The registered tool validates its input before passing it to the sandbox and returns the sandbox result rather than raising for an ordinary script error.

## As a tool

The server-name prefix defaults to `python`, so the registered function is `python.execute`.

| Function | Description |
|---|---|
| `python.execute` | Run Python source in the restricted sandbox. |

`code` is required and must be a non-empty string. Use `print()` for visible output and assign a JSON-compatible value to `result` to return it structurally. The response has `stdout`, `stderr`, `exit_code` (0 success, 1 exception, -1 timeout), `timed_out`, and `result`; blocked imports or invalid code are reported through that result.

## Configuration

Start with the default timeout and no additional modules. The server name is normally only changed to avoid a tool-name collision.

### Execution timeout (seconds)

The value is clamped to 1–1200 seconds; absent or invalid input uses the sandbox default. Raise it only for a computation that genuinely needs longer, because an agent call remains occupied until the sandbox returns or times out.

### Additional Allowed Modules

Each configured module name is added to the sandbox's import allowlist. Keep this list empty for the narrowest environment; add a module only when the agent needs it and you accept the capabilities that module exposes. The tool description tells the agent the effective allowed-import list, and every other import raises `ImportError`.

## Notes

### Sandbox boundary

The node uses RestrictedPython's restricted compiler and safe builtins. A tool call requires a JSON object; a missing, blank, or non-string `code` value raises a validation error before execution.

## Upstream docs

- [RestrictedPython documentation](https://restrictedpython.readthedocs.io/)

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

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_python.allowedModules` | `array` | **Additional Allowed Modules**<br/>Modules the agent is allowed to import, in addition to the built-in defaults (math, json, re, collections, datetime, etc.). This setting has no effect on RocketRide Cloud, where only the built-in defaults can be imported. |  |
| `tool_python.moduleName` | `string` | **Module name** | `""` |
| `tool_python.serverName` | `string` | **Server name**<br/>Namespace prefix for the tool: <serverName>.execute | `"python"` |
| `tool_python.timeout` | `integer` | **Execution timeout (seconds)**<br/>Maximum seconds a script may run before it is killed. Default is 20s, max is 1200s. | `20` |

## 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_python)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->
