# Code Execution Nodes

> Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: `crates/cheng-nodes/src/nodes/builtin/tools`, `crates/cheng-runtime/src`

Script execution, sandboxed. `tools/code_shell` is available by default; `tools/code_python` and
`tools/code_js` are gated by the `CHENG_ENABLE_CODE_PYTHON` and `CHENG_ENABLE_CODE_JS` environment
variables and simply do not register when those are unset. Anything the script needs from outside the
sandbox goes through the read-path request field, and each requested path needs human approval for
that execution. `tools/runtime` is not a script node: it expands a configured tool bundle for an
agent and executes one call from it.

## Shell Executor — `tools/code_shell`

Run shell scripts in a bubblewrap sandbox (OS-namespace isolation: PID/IPC/UTS/network). FAIL-CLOSED: errors if bubblewrap is unavailable — no silent downgrade. Use for: curl, wget, system commands, file operations, pipeline processing, any external process. Do NOT use for pure computation (→ JS) or data transformation (→ Python). Requires allow_network=true for outbound HTTP. Example: {"script":"curl -s 'wttr.in/Tokyo?format=3'","allow_network":true}

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `input` | any | — | `null` | Input data (any JSON), accessible via $INPUT environment variable in script |
| `script` | string | — | `null` | [Required] Shell script. Example: curl -s 'wttr.in/Tokyo?format=3'. Control: `code-editor` |
| `working_subdir` | string | — | `null` | Relative working subdirectory inside the execution boundary (e.g. project-alpha). Selects the process cwd only; cannot widen filesystem access. |
| `allow_filesystem` | boolean | — | `false` | Whether to allow script to write files to workspace. Control: `switch` |
| `allow_full_disk_readonly` | boolean | — | `false` | Whether to allow read-only access to entire disk (for disk-wide search/file finding). Writing still requires allow_filesystem. Control: `switch` |
| `request_read_paths` | array<string> | — | `[]` | Absolute host paths to request READ-ONLY access to, outside the sandbox (e.g. /home/me/project). Each one needs human approval for this execution; approved paths are mounted read-only. Use only when the script must read files the sandbox cannot see. |
| `allow_network` | boolean | — | `false` | Whether to allow network access (curl, HTTP requests etc. need to be true). Control: `switch` |
| `timeout_ms` | integer | — | `5000` | Timeout in milliseconds. Default 5000ms, max 300000ms. Control: `number` |
| `memory_mb` | integer | — | `128` | Memory limit in MB. Enforced via prlimit under Bubblewrap. Default 128MB. Control: `number` |
| `disable_sandbox` | boolean | — | `false` | Request to run on the host WITHOUT any sandbox: full filesystem, network and command access as the ChengFlow system account. Requires human approval for this execution. Use only for host troubleshooting. Control: `switch` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `result` | any | Result returned by the script |
| `isolation_level` | string | Actual isolation level used by the runtime: bubblewrap, quickjs, python, shell, or container |
| `metrics` | object | Runtime execution metrics |
| `stdout` | string | Standard output stream |
| `stderr` | string | Standard error stream |
| `warnings` | array<string> | Validation warnings generated before execution |

## Python Executor — `tools/code_python`

Run Python 3 scripts in a bubblewrap sandbox (OS-namespace isolation shared with the Shell node). FAIL-CLOSED: errors if the secure launcher or python3 is unavailable — never downgrades to native host execution. Use for algorithms, text processing, data transformation, and scientific computing. Do not use it for network requests (use Shell) or simple JSON/string transformations (use JavaScript). Network access is disabled by design. The JSON input is available as the `input` variable.

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `input` | any | — | `null` | JSON input exposed to the script as `input` |
| `script` | string | — | `null` | [Required] Python 3 script. Example: `result = sum(input['values'])`. Control: `code-editor` |
| `working_subdir` | string | — | `null` | Relative working subdirectory inside the execution boundary (e.g. project-alpha). Selects the process cwd only; cannot widen filesystem access. |
| `allow_filesystem` | boolean | — | `false` | Whether to allow the script to write files to the workspace. Control: `switch` |
| `allow_full_disk_readonly` | boolean | — | `false` | Whether to allow read-only access to the entire disk for disk-wide search and file finding. Control: `switch` |
| `request_read_paths` | array<string> | — | `[]` | Absolute host paths to request READ-ONLY access to, outside the sandbox (e.g. /home/me/project). Each one needs human approval for this execution; approved paths are mounted read-only. Use only when the script must read files the sandbox cannot see. |
| `timeout_ms` | integer | — | `5000` | Timeout in milliseconds. Default: 5000 ms. Maximum: 300000 ms. Control: `number` |
| `memory_mb` | integer | — | `128` | Memory limit in MB. Hard-enforced via cgroup v2 when available, prlimit fallback otherwise. Default: 128 MB. Control: `number` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `result` | any | Result returned by the script |
| `isolation_level` | string | Actual isolation level used by the runtime: bubblewrap, quickjs, python, shell, or container |
| `metrics` | object | Runtime execution metrics |
| `stdout` | string | Standard output stream |
| `stderr` | string | Standard error stream |
| `warnings` | array<string> | Validation warnings generated before execution |

## JavaScript Executor — `tools/code_js`

Run JavaScript in a QuickJS sandbox with no syscalls, network, or filesystem access. Fail closed if QuickJS is unavailable. Use this node for pure computation, JSON/object transformation, string manipulation, and math. Do not use it for network requests (use Shell) or library-heavy data processing (use Python).

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `input` | any | — | `null` | JSON input exposed to the script as `input` |
| `script` | string | — | `null` | [Required] JavaScript script. The value of the final expression is returned as `result`. Control: `code-editor` |
| `timeout_ms` | integer | — | `5000` | Timeout in milliseconds. Default: 5000 ms. Maximum: 300000 ms. Control: `number` |
| `memory_mb` | integer | — | `128` | Memory limit in MB. QuickJS enforces this as an internal soft limit. Default: 128 MB. Control: `number` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `result` | any | Result returned by the script |
| `isolation_level` | string | Actual isolation level used by the runtime: bubblewrap, quickjs, python, shell, or container |
| `metrics` | object | Runtime execution metrics |
| `stdout` | string | Standard output stream |
| `stderr` | string | Standard error stream |
| `warnings` | array<string> | Validation warnings generated before execution |

## Tool Runtime — `tools/runtime`

A configurable tool bundle: connect once to an LLM/Agent and expose a curated, policy-bounded set of tools.

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `action` | enum | — | `list_tools` | list_tools \| execute \| validate_config. Options: `list_tools` (Expand the bundle into LLM function definitions.), `execute` (Execute a single tool call through the runtime.), `validate_config` (Statically validate the configured bundle.) |
| `tool_call` | object | — | — | Tool call for action=execute |
| `exposed_tools` | array<object> | — | `[]` | Curated tool bundle |
| `dry_run` | boolean | — | `false` | Validate without dispatching |

### Outputs

| Field | Type | Description |
|---|---|---|
| `status` | string | Runtime action status |
| `functions` | array<any> | Expanded LLM functions |
| `result` | any | Tool execution result |
| `errors` | array<string> | Configuration errors |
| `warnings` | array<string> | Configuration warnings |

## Next steps

- [Workspace Tool Nodes](/docs/nodes-workspace-tools)
- [File Operation Nodes](/docs/nodes-file-ops)
- [Writing a Custom Node](/docs/dev-custom-node)