Skip to main content

Source: docs/manual/python-exec.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Python Exec Tool

The python_exec tool executes Python code inside a constrained sandbox. It is designed for data processing, small transformations, and quick calculations with controlled resource usage.

Schema​

{
  "type": "object",
  "required": ["code"],
  "properties": {
    "code": {"type": "string", "description": "Python source code to execute."},
    "timeout_ms": {"type": "integer", "description": "Timeout in milliseconds (default 2000)."},
    "input": {"description": "Optional JSON input bound to variable 'input'."},
    "max_output_kb": {"type": "integer", "description": "Override stdout/stderr limit in KB (bounded)."},
    "max_file_kb": {"type": "integer", "description": "Override max file size in KB (bounded)."},
    "result_schema": {"type": "object", "description": "Optional JSON schema to validate result_json."},
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["path", "content"],
        "properties": {
          "path": {"type": "string"},
          "content": {"type": "string"}
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

Output​

The tool returns JSON with:

  • stdout (string)
  • stderr (string)
  • exit_code (int)
  • result_json (optional JSON) extracted from a result variable in the user code.

Example code:

result = {"sum": input["a"] + input["b"]}

Sandbox Limits​

Defaults (configurable in code):

  • Timeout: 2 seconds (timeout_ms overrides per call)
  • CPU: 2 seconds (RLIMIT_CPU)
  • Memory: 256 MB (RLIMIT_AS)
  • Stdout/Stderr: 64 KB total each
  • File content size: 256 KB per file

Network and subprocess usage are blocked by the Python runner policy. Writes are restricted to the sandbox work directory. Execution is routed through CRUVERO_SANDBOX_MODE (process|gvisor|nsjail) with automatic fallback to process when the selected runtime is unavailable.

Import Allowlist​

Default allowlist:

  • Stdlib/core: _csv, _datetime, _io, base64, binascii, bisect, collections, copy, csv, dataclasses, datetime, decimal, enum, fractions, functools, hashlib, heapq, io, itertools, json, math, numbers, operator, pathlib, pprint, random, re, string, statistics, textwrap, time, typing, uuid
  • Data stack: numpy, pandas, sympy, scipy, dateutil, pytz, requests

Environment Overrides​

  • CRUVERO_PYTHON_ALLOW_ALL_IMPORTS = true|false (default false)
  • CRUVERO_PYTHON_BLOCK_IMPORTS (comma-separated import blocklist, applied even when allow-all is true)
  • CRUVERO_PYTHON_MAX_CPU_SECS (default 2)
  • CRUVERO_PYTHON_MAX_MEM_MB (default 256)
  • CRUVERO_PYTHON_MAX_OUTPUT_KB (default 64)
  • CRUVERO_PYTHON_MAX_FILE_KB (default 256)
  • CRUVERO_SANDBOX_MODE (process|gvisor|nsjail, default process)

Per-Call Overrides​

  • max_output_kb (lower than env max only)
  • max_file_kb (lower than env max only)
  • result_schema (JSON Schema for validating result_json)

Runtime Manifest​

Use the manifest helper to record actual versions in your environment:

go run ./cmd/python-manifest

This prints JSON with the Python runtime and package versions installed on the host.

Security Notes​

  • Imports outside the allowlist are blocked unless CRUVERO_PYTHON_ALLOW_ALL_IMPORTS=true.
  • CRUVERO_PYTHON_BLOCK_IMPORTS always blocks listed imports, even when allow-all is enabled.
  • Network access is blocked at the socket layer.
  • Subprocess creation is blocked.
  • Writes are limited to the sandbox directory.