Code Execution Tools

ClawCentral provides sandboxed code execution through a containerized environment. Execute Python, shell, and Node.js code directly from conversations.

Availability

Code execution requires the CODE_EXECUTOR binding to be configured. This is available in ClawCentral's managed platform.

Overview

Four tools are available for code execution:

Tool	Description
execute_python	Run Python code in a persistent REPL
execute_shell	Execute bash shell commands
execute_node	Run Node.js code
reset_repl	Clear the Python REPL state

execute_python

Execute Python code in a persistent interpreter session. Variables and imports survive across calls.

Parameters:

Parameter	Type	Required	Description
code	string	Yes	Python code to execute
timeout	number	No	Timeout in seconds (default 30, max 120)

Example:

{
  "code": "import pandas as pd\ndf = pd.DataFrame({'a': [1,2,3]})\nprint(df.mean())"
}

Returns:

{
  "stdout": "a    2.0\ndtype: float64\n",
  "stderr": "",
  "error": null
}

Notes:

• The Python environment includes common packages (pandas, numpy, etc.)
• Variables persist within the same session
• Filesystem is ephemeral — use workspace tools to persist files

execute_shell

Run a shell command in a bash environment.

Parameters:

Parameter	Type	Required	Description
command	string	Yes	Shell command to run
timeout	number	No	Timeout in seconds (default 30, max 120)

Example:

{
  "command": "curl -s https://api.example.com/data"
}

Returns:

{
  "stdout": "response body...\n",
  "stderr": "",
  "error": null
}

Notes:

• Use for curl, git, running scripts, etc.
• Filesystem is ephemeral — use workspace tools to persist files
• Network access is available

execute_node

Execute Node.js code in a JavaScript runtime.

Parameters:

Parameter	Type	Required	Description
code	string	Yes	Node.js code to execute
timeout	number	No	Timeout in seconds (default 30, max 120)

Example:

{
  "code": "const fs = require('fs');\nconsole.log(process.version);"
}

Returns:

{
  "stdout": "v20.10.0\n",
  "stderr": "",
  "error": null
}

Notes:

• State is not persisted between calls (unlike Python)
• Standard Node.js APIs are available
• npm packages are not pre-installed

reset_repl

Reset the Python REPL session, clearing all variables and imports.

Parameters: None

Example:

{}

Returns:

{
  "stdout": "Python REPL reset.\n",
  "stderr": "",
  "error": null
}

Use this when you want to start fresh without accumulated state from previous executions.

Container Lifecycle

The code execution environment runs in a Cloudflare Container:

• Cold start: ~2-5 seconds when the container is not running
• Idle timeout: Container sleeps after 5 minutes of inactivity
• Persistence: Python REPL state persists within a session
• Ephemeral filesystem: Files created during execution do not persist

Timeout Behavior

All tools support a configurable timeout:

• Default: 30 seconds
• Maximum: 120 seconds
• Behavior: Returns partial output + timeout error if exceeded

Error Handling

All tools return a consistent error format:

{
  "stdout": "partial output...\n",
  "stderr": "error details\n",
  "error": "Error: timeout exceeded"
}

When error is non-null, the execution failed. Check stderr for details.

Related

• Tools Overview — All available agent tools
• Exec Approvals — Approval configuration for shell commands
• Workspace — Persistent workspace for files