Sandbox Code Executor

Relevant source files

• agent/tools/code_exec.py
• agent/tools/exesql.py
• internal/agent/component/fixture_stubs.go
• internal/agent/component/invoke.go
• internal/agent/component/invoke_test.go
• internal/agent/component/production_chain_fixes_test.go
• internal/agent/component/tool_component_test.go
• internal/agent/component/universe_a_wrappers.go
• internal/agent/component/verify_p1_test.go
• internal/agent/runtime/state.go
• internal/agent/runtime/state_test.go
• internal/agent/sandbox/self_managed.go
• internal/agent/tool/arxiv.go
• internal/agent/tool/arxiv_test.go
• internal/agent/tool/email.go
• internal/agent/tool/github.go
• internal/agent/tool/github_test.go
• internal/agent/tool/google_scholar.go
• internal/agent/tool/google_scholar_test.go
• internal/agent/tool/keenable.go
• internal/agent/tool/keenable_test.go
• internal/agent/tool/pubmed.go
• internal/agent/tool/pubmed_test.go
• internal/agent/tool/registry.go
• internal/agent/tool/registry_test.go
• internal/agent/tool/wikipedia.go
• internal/agent/tool/wikipedia_test.go
• internal/agent/tool/yahoo_finance.go
• internal/agent/tool/yahoo_finance_test.go
• internal/harness/core/interrupt.go
• test/unit_test/agent/tools/test_exesql_ssrf.py
• web/src/pages/agent/form/exesql-form/index.tsx
• web/src/pages/agent/form/exesql-form/use-submit-form.ts
• web/src/pages/agent/form/tool-form/exesql-form/index.tsx
• web/src/pages/agent/options.ts
• web/src/pages/next-chats/hooks/use-build-form-refs.ts

The Sandbox Code Executor is a secure, multi-provider execution environment designed to run arbitrary Python or JavaScript code within RAGFlow agent workflows. It provides a pluggable architecture that supports local execution, self-managed gVisor-based containers, and SaaS solutions. This system ensures that user-provided scripts are isolated from the host environment while maintaining high-performance data exchange with the workflow engine.

System Architecture

The sandbox system follows a provider-based pattern managed by a central provider manager. It abstracts the underlying execution technology (containers, microVMs, or processes) from the agent components.

Natural Language to Code Entity Mapping

The following diagrams illustrate how user-defined logic in the RAGFlow Canvas translates into backend execution entities and how data flows through the system.

Workflow to Execution Mapping

Sources: agent/tools/code_exec.py29 agent/tools/code_exec.py205-208 agent/tools/code_exec.py245-255

Data and Component Integration Flow

Sources: agent/tools/code_exec.py183-199 agent/tools/code_exec.py107-115

Provider Implementations

RAGFlow supports multiple sandbox backends, configured via system settings. The backend selection determines the level of isolation and resource overhead. In the Go-side implementation (internal/agent/sandbox/), the provider system handles lifecycle management for various platforms.

Provider	Class / Service	Description
Self-Managed	SelfManagedProvider	A dedicated service running gVisor-protected containers, implemented in internal/agent/sandbox/self_managed.go.
Aliyun	AliyunCodeInterpreterProvider	Integrates with Aliyun Function Compute for serverless microVM execution.
Local	LocalProvider	Executes code as a local child process using the host's runtime. Intended for trusted development only.
E2B	E2BProvider	Utilizes the E2B sandbox cloud for secure code execution.

Sources: agent/tools/code_exec.py205-208 internal/agent/sandbox/self_managed.go1-15

Execution Lifecycle

The lifecycle of a code execution task is managed through the SandboxProvider interface.

1. Initialization: The system loads the provider class and initializes it with settings from the configuration (e.g., SANDBOX_MAX_MEMORY, SANDBOX_TIMEOUT).
2. Instance Creation: The system prepares the environment. For the self_managed provider, this involves checking for available containers in the pool.
3. Code Wrapping: Raw user code is wrapped in boilerplate to handle argument passing and result serialization. A wrapper script calls the user's main(**arguments) function and serializes the return value to stdout.
4. Execution: The code is executed with a timeout, typically governed by COMPONENT_EXEC_TIMEOUT (default 60s) agent/tools/exesql.py73
5. Result Extraction: The system parses the process output to find specific markers, extracting the JSON return value and any generated logs agent/tools/code_exec.py183-199
6. Cleanup: The execution environment is reset or destroyed to prevent state leakage between workflow runs.

Sources: agent/tools/code_exec.py183-199 agent/tools/exesql.py73

Security and Constraints

Type Validation

The CodeExec tool enforces a strict contract between the sandbox and the engine via the build_code_exec_contract function agent/tools/code_exec.py183-199

• Reserved Keys: Scripts cannot return keys that conflict with system outputs like content, actual_type, attachments, _ERROR, _ARTIFACTS, _ATTACHMENT_CONTENT, raw_result, _created_time, or _elapsed_time agent/tools/code_exec.py36-48
• Schema Enforcement: _validate_expected_type recursively checks that the returned data matches the expected type (e.g., String, Number, Array<Object>) agent/tools/code_exec.py149-181
• Domain Validation: Only JSON-serializable types (String, Number, Boolean, Object, Array, Null) are allowed as top-level results agent/tools/code_exec.py122-126

Variable Resolution

The sandbox receives input variables resolved from the workflow context. These are passed as a dictionary to the script's entry point. The CodeExec component uses variable resolution logic to resolve and inject these variables before execution agent/tools/exesql.py102-112

SSRF Protection

For tools that interact with external databases like ExeSQL, RAGFlow implements an SSRF guard. The assert_host_is_safe function ensures that user-provided hosts do not resolve to internal, loopback, or restricted network addresses agent/tools/exesql.py122-128

Integration with Agent Workflow

The Sandbox is the backbone of the Code component, implemented by the CodeExec class agent/tools/code_exec.py29

Artifact Management

If the code generates files (e.g., charts or dataframes), providers collect them. These are base64-encoded and returned in the execution result, then uploaded to the SANDBOX_ARTIFACT_BUCKET in MinIO agent/tools/code_exec.py33 Artifacts are assigned expiration based on SANDBOX_ARTIFACT_EXPIRE_DAYS agent/tools/code_exec.py33

Go-Side Integration

In the Go agent port, the code_exec tool is registered in the global tool registry internal/agent/tool/registry.go37 The NewCodeExecTool provides the Eino-compatible interface for the canvas internal/agent/tool/registry.go37 For testing purposes, CodeExec is also represented in the fixture_stubs.go to allow e2e canvas flows to run without an active sandbox internal/agent/component/fixture_stubs.go173

Language Support

The sandbox primarily supports Python and Node.js. In the agent canvas, users can select languages and configure parameters that are eventually passed to the CodeExec component. Supported languages are defined in the Language enum agent/tools/code_exec.py205-207

Troubleshooting

Error	Root Cause	Resolution
ContractError	Output name is empty, contains ., or is a reserved key agent/tools/code_exec.py51-62	Rename the output variable in the Code component.
TimeoutError	Code execution exceeded the defined timeout.	Optimize code or increase COMPONENT_EXEC_TIMEOUT in the environment agent/tools/exesql.py73
Type Mismatch	The script returned a type that does not match the component configuration agent/tools/code_exec.py183-192	Update the expected type in the UI or fix the script return value.

Sources: agent/tools/code_exec.py51-62 agent/tools/code_exec.py183-192 agent/tools/exesql.py73 internal/agent/tool/registry.go37 internal/agent/component/fixture_stubs.go173