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