Task Runners and Code Execution

Relevant source files

• .github/workflows/ci-python.yml
• packages/@n8n/benchmark/src/n8n-api-client/n8n-api-client.ts
• packages/@n8n/config/src/configs/endpoints.config.ts
• packages/@n8n/config/src/configs/runners.config.ts
• packages/@n8n/config/src/configs/scaling-mode.config.ts
• packages/@n8n/nodes-langchain/nodes/trigger/ChatTrigger/GenericFunctions.ts
• packages/@n8n/nodes-langchain/nodes/trigger/ChatTrigger/__test__/GenericFunctions.test.ts
• packages/@n8n/nodes-langchain/nodes/trigger/ChatTrigger/__test__/templates.test.ts
• packages/@n8n/task-runner-python/.python-version
• packages/@n8n/task-runner-python/README.md
• packages/@n8n/task-runner-python/justfile
• packages/@n8n/task-runner-python/pyproject.toml
• packages/@n8n/task-runner-python/src/config/health_check_config.py
• packages/@n8n/task-runner-python/src/config/security_config.py
• packages/@n8n/task-runner-python/src/config/sentry_config.py
• packages/@n8n/task-runner-python/src/config/task_runner_config.py
• packages/@n8n/task-runner-python/src/constants.py
• packages/@n8n/task-runner-python/src/env.py
• packages/@n8n/task-runner-python/src/errors/__init__.py
• packages/@n8n/task-runner-python/src/errors/configuration_error.py
• packages/@n8n/task-runner-python/src/errors/invalid_pipe_msg_content_error.py
• packages/@n8n/task-runner-python/src/errors/invalid_pipe_msg_length_error.py
• packages/@n8n/task-runner-python/src/errors/security_violation_error.py
• packages/@n8n/task-runner-python/src/errors/task_result_read_error.py
• packages/@n8n/task-runner-python/src/errors/task_runtime_error.py
• packages/@n8n/task-runner-python/src/errors/task_subprocess_failed_error.py
• packages/@n8n/task-runner-python/src/health_check_server.py
• packages/@n8n/task-runner-python/src/import_validation.py
• packages/@n8n/task-runner-python/src/logs.py
• packages/@n8n/task-runner-python/src/main.py
• packages/@n8n/task-runner-python/src/message_serde.py
• packages/@n8n/task-runner-python/src/message_types/__init__.py
• packages/@n8n/task-runner-python/src/message_types/broker.py
• packages/@n8n/task-runner-python/src/message_types/pipe.py
• packages/@n8n/task-runner-python/src/message_types/runner.py
• packages/@n8n/task-runner-python/src/nanoid.py
• packages/@n8n/task-runner-python/src/pipe_reader.py
• packages/@n8n/task-runner-python/src/sentry.py
• packages/@n8n/task-runner-python/src/task_analyzer.py
• packages/@n8n/task-runner-python/src/task_executor.py
• packages/@n8n/task-runner-python/src/task_runner.py
• packages/@n8n/task-runner-python/src/task_state.py
• packages/@n8n/task-runner-python/tests/fixtures/local_task_broker.py
• packages/@n8n/task-runner-python/tests/fixtures/task_runner_manager.py
• packages/@n8n/task-runner-python/tests/fixtures/test_constants.py
• packages/@n8n/task-runner-python/tests/integration/conftest.py
• packages/@n8n/task-runner-python/tests/integration/test_execution.py
• packages/@n8n/task-runner-python/tests/integration/test_health_check.py
• packages/@n8n/task-runner-python/tests/integration/test_rpc.py
• packages/@n8n/task-runner-python/tests/unit/test_env.py
• packages/@n8n/task-runner-python/tests/unit/test_sentry.py
• packages/@n8n/task-runner-python/tests/unit/test_task_analyzer.py
• packages/@n8n/task-runner-python/tests/unit/test_task_executor.py
• packages/@n8n/task-runner-python/uv.lock
• packages/@n8n/task-runner/src/config/base-runner-config.ts
• packages/@n8n/task-runner/src/data-request/__tests__/data-request-response-reconstruct.test.ts
• packages/@n8n/task-runner/src/data-request/data-request-response-reconstruct.ts
• packages/@n8n/task-runner/src/index.ts
• packages/@n8n/task-runner/src/js-task-runner/__tests__/js-task-runner.test.ts
• packages/@n8n/task-runner/src/js-task-runner/__tests__/task-runner.test.ts
• packages/@n8n/task-runner/src/js-task-runner/__tests__/test-data.ts
• packages/@n8n/task-runner/src/js-task-runner/built-ins-parser/__tests__/built-ins-parser-state.test.ts
• packages/@n8n/task-runner/src/js-task-runner/built-ins-parser/__tests__/built-ins-parser.test.ts
• packages/@n8n/task-runner/src/js-task-runner/built-ins-parser/built-ins-parser-state.ts
• packages/@n8n/task-runner/src/js-task-runner/built-ins-parser/built-ins-parser.ts
• packages/@n8n/task-runner/src/js-task-runner/errors/task-cancelled-error.ts
• packages/@n8n/task-runner/src/js-task-runner/errors/timeout-error.ts
• packages/@n8n/task-runner/src/js-task-runner/js-task-runner.ts
• packages/@n8n/task-runner/src/message-types.ts
• packages/@n8n/task-runner/src/runner-types.ts
• packages/@n8n/task-runner/src/start.ts
• packages/@n8n/task-runner/src/task-runner.ts
• packages/cli/BREAKING-CHANGES.md
• packages/cli/src/abstract-server.ts
• packages/cli/src/commands/base-command.ts
• packages/cli/src/modules/redaction/__tests__/redaction.module.test.ts
• packages/cli/src/modules/redaction/executions/__tests__/execution-redaction.service.test.ts
• packages/cli/src/modules/redaction/executions/execution-redaction.service.ts
• packages/cli/src/modules/redaction/redaction.module.ts
• packages/cli/src/scaling/__tests__/worker-server.test.ts
• packages/cli/src/scaling/worker-server.ts
• packages/cli/src/server.ts
• packages/cli/src/services/__tests__/redis-client.service.test.ts
• packages/cli/src/services/redis-client.service.ts
• packages/cli/src/task-runners/task-broker/task-broker-server.ts
• packages/cli/test/integration/execution-redaction.test.ts
• packages/cli/test/integration/shared/types.ts
• packages/cli/test/integration/shared/utils/test-server.ts
• packages/core/src/errors/error-reporter.ts
• packages/frontend/editor-ui/src/app/composables/useBackendStatus.spec.ts
• packages/frontend/editor-ui/src/app/composables/useBackendStatus.ts
• packages/nodes-base/nodes/Code/PythonTaskRunnerSandbox.ts
• packages/nodes-base/nodes/Code/test/PythonTaskRunnerSandbox.test.ts

Overview

The Task Runner system provides isolated, sandboxed execution environments for user-provided JavaScript and Python code in n8n workflows. This architecture separates code execution from the main n8n process, enhancing security and stability by preventing untrusted code from directly accessing n8n internals or the host system.

The system consists of three main components:

• Task Runner Launcher: A Go binary that manages runner processes and handles communication
• JavaScript Task Runner: Node.js-based runner for executing JavaScript code
• Python Task Runner: Python-based runner for executing Python code

Task runners are deployed as separate containers (sidecar pattern) or processes that communicate with the main n8n application over HTTP.

Key Benefits:

• Security Isolation: Code runs in separate processes with restricted capabilities
• Resource Management: Individual runners can be scaled and monitored independently
• Fault Tolerance: Code execution failures don't crash the main application
• Language Support: Extensible architecture supports multiple runtime environments

Sources: docker/images/runners/Dockerfile docker/images/runners/Dockerfile.distroless

---

System Architecture

Communication Flow:

1. Code Node in n8n workflow sends execution task to Task Broker
2. Task Broker forwards HTTP request to task-runner-launcher
3. Launcher routes request to appropriate runner (JavaScript or Python)
4. Runner executes code in sandboxed environment
5. Result flows back through launcher to n8n main process

Sources: docker/images/runners/n8n-task-runners.json docker/images/runners/Dockerfile142-148

---

Task Runner Launcher

The Task Runner Launcher is an external Go binary that manages the lifecycle of task runner processes and acts as an HTTP gateway between n8n and the individual runners.

Key Responsibilities

Responsibility	Description
Process Management	Starts, monitors, and stops JavaScript and Python runner processes
Request Routing	Routes incoming task requests to the appropriate runner based on task type
Health Monitoring	Monitors runner health via HTTP health check endpoints
Configuration	Loads runner configuration from /etc/n8n-task-runners.json
Auto-shutdown	Terminates idle runners after configured timeout

Installation and Version

The launcher binary is downloaded during Docker image build from the n8n-io/task-runner-launcher GitHub repository:

The launcher is installed to /usr/local/bin/ and serves as the container entrypoint.

Sources: docker/images/runners/Dockerfile82-101 docker/images/runners/Dockerfile.distroless98-120

Configuration Format

The launcher reads configuration from /etc/n8n-task-runners.json:

Configuration Fields:

• runner-type: Identifies the runner (must match task type in requests)
• workdir: Working directory for the runner process
• command: Path to the runtime executable (node or python)
• args: Command-line arguments passed to the runner
• health-check-server-port: Port for HTTP health checks
• allowed-env: Whitelist of environment variables passed to runner
• env-overrides: Environment variables set/overridden by launcher

Sources: docker/images/runners/n8n-task-runners.json1-55

---

JavaScript Task Runner

The JavaScript task runner executes JavaScript code from Code nodes using a sandboxed Node.js environment.

Runtime Configuration

Security Flags:

• --disallow-code-generation-from-strings: Prevents eval(), Function(), etc.
• --disable-proto=delete: Removes __proto__ to prevent prototype pollution

Sources: docker/images/runners/n8n-task-runners.json7-10

Package Structure

The JavaScript runner is built from the @n8n/task-runner package and installed to /opt/runners/task-runner-javascript/:

The build process removes monorepo-specific dependency references (catalog:, workspace:) to allow users to extend the image with pnpm add.

Sources: docker/images/runners/Dockerfile7-32

Allowed Libraries

Default allowed libraries are configured via environment variables:

Environment Variable	Default Value	Purpose
NODE_FUNCTION_ALLOW_BUILTIN	crypto	Whitelisted Node.js built-in modules
NODE_FUNCTION_ALLOW_EXTERNAL	moment	Whitelisted external npm packages

These can be overridden by setting environment variables when starting the container. The moment library is pre-installed for backwards compatibility with existing workflows.

Sources: docker/images/runners/n8n-task-runners.json27-28

---

Python Task Runner

The Python task runner executes Python code from Code nodes using a sandboxed Python environment.

Runtime Configuration

Python Flags:

• -I: Isolated mode (ignores user environment, site-packages)
• -B: Don't write .pyc files (security)
• -X disable_remote_debug: Disables remote debugging capabilities

Sources: docker/images/runners/n8n-task-runners.json36

Package Management with uv

The Python runner uses uv (fast Python package installer) to create a reproducible virtual environment:

This creates a relocatable virtual environment at /opt/runners/task-runner-python/.venv/ that includes all dependencies.

Sources: docker/images/runners/Dockerfile37-79

Allowed Libraries

Library access is controlled via environment variables:

Environment Variable	Default Value	Purpose
N8N_RUNNERS_STDLIB_ALLOW	"" (empty)	Whitelisted Python standard library modules
N8N_RUNNERS_EXTERNAL_ALLOW	"" (empty)	Whitelisted external packages

By default, both are empty strings, meaning strict sandboxing. Users can extend the image with additional packages:

Then restart with updated environment variables to allow their use.

Sources: docker/images/runners/n8n-task-runners.json50-51

---

Docker Images

n8n provides two Docker images for task runners:

Alpine-Based Image (Default)

Image: n8nio/runners:latest
Base: python:3.13-alpine + node:24.13.1-alpine

Characteristics:

• Small image size (~200MB compressed)
• Includes shell and package managers (pnpm, uv)
• Suitable for development and self-hosted deployments
• Easy to extend with additional packages

Sources: docker/images/runners/Dockerfile110-155

Distroless Image (Hardened)

Image: n8nio/runners:latest-distroless
Base: gcr.io/distroless/cc-debian12

Characteristics:

• No shell, no package managers, no system utilities
• Runs as non-root user (UID 65532)
• Smaller attack surface
• Preferred for cloud/production deployments
• Cannot be extended at runtime (must rebuild image)

Sources: docker/images/runners/Dockerfile.distroless128-199

Multi-Architecture Support

Both images are built for AMD64 and ARM64 architectures using multi-stage builds in GitHub Actions:

The workflow builds platform-specific images (-amd64, -arm64 suffixes) then combines them into multi-arch manifest tags.

Sources: .github/workflows/docker-build-push.yml136-167 .github/workflows/docker-build-push.yml197-230

---

Deployment and Configuration

Sidecar Container Pattern

Task runners are typically deployed as sidecar containers alongside the main n8n container:

Key Environment Variables:

Variable (n8n)	Purpose
N8N_RUNNERS_ENABLED	Enable task runner integration
N8N_RUNNERS_MODE	external for sidecar, internal for in-process
N8N_RUNNERS_TASK_BROKER_URI	HTTP endpoint for task runner launcher

Variable (runners)	Purpose
N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT	Seconds of inactivity before runner shutdown
N8N_RUNNERS_TASK_TIMEOUT	Maximum execution time per task (seconds)
N8N_RUNNERS_MAX_CONCURRENCY	Maximum concurrent task executions

Health Monitoring

Each runner exposes an HTTP health check endpoint:

• JavaScript runner: http://localhost:5681/healthz
• Python runner: http://localhost:5682/healthz

The launcher monitors these endpoints and restarts failed runners automatically.

Sources: docker/images/runners/n8n-task-runners.json12 docker/images/runners/n8n-task-runners.json37

---

Security and Isolation

Process-Level Isolation

• Separate container provides network and filesystem isolation
• Non-root user (UID 1000 or 65532 for distroless)
• Runner processes managed as child processes of launcher
• No direct communication between n8n and runner processes

Sources: docker/images/runners/Dockerfile134-135 docker/images/runners/Dockerfile.distroless187

Code Sandboxing

JavaScript:

• Node.js flags prevent code generation from strings (eval, Function)
• Prototype pollution protections (--disable-proto=delete)
• Limited access to Node.js built-in modules (whitelist-based)
• External packages must be explicitly allowed

Python:

• Isolated mode (-I) prevents importing from user site-packages
• RestrictedPython limits access to dangerous operations
• Standard library access controlled via whitelist
• External packages require explicit installation and allowlisting

Sources: docker/images/runners/n8n-task-runners.json8-10 docker/images/runners/n8n-task-runners.json36

Environment Variable Filtering

The launcher enforces strict environment variable filtering:

Only explicitly allowed environment variables are passed from the host to runner processes. This prevents sensitive information leakage (credentials, tokens, etc.).

Sources: docker/images/runners/n8n-task-runners.json13-25 docker/images/runners/n8n-task-runners.json38-48

---

Build Pipeline and Release

CI/CD Workflow

The task runner images are built and published alongside the main n8n image:

Build Steps:

1. Compile @n8n/task-runner and @n8n/task-runner-python packages
2. Build Alpine and distroless images for each architecture
3. Create multi-architecture manifests combining AMD64 and ARM64 builds
4. Generate SLSA L3 provenance attestations for supply chain security
5. Attach VEX (Vulnerability Exploitability eXchange) documents
6. Publish to GitHub Container Registry and DockerHub

Sources: .github/workflows/docker-build-push.yml70-167 .github/workflows/docker-build-push.yml279-331

Security Scanning

Both runner images undergo security scanning with Trivy:

Vulnerability reports are generated for each release and tracked via VEX attestations.

Sources: .github/workflows/docker-build-push.yml398-410

---

Extending Runner Images

Adding JavaScript Packages

To extend the JavaScript runner with additional npm packages:

The Alpine-based image includes pnpm by default, allowing package installation.

Adding Python Packages

To extend the Python runner with additional Python packages:

The Alpine-based image includes uv by default for fast package installation.

Distroless Limitations

The distroless image cannot be extended at runtime because it lacks shell and package managers. To add packages, rebuild from source:

Sources: docker/images/runners/Dockerfile129-133 docker/images/runners/Dockerfile119

---

Summary

The Task Runner system provides a secure, isolated architecture for executing user code in n8n:

Component	Purpose	Key Technologies
Task Runner Launcher	Process manager and HTTP gateway	Go binary, external repository
JavaScript Runner	Execute JavaScript code	Node.js, vm2/isolated-vm
Python Runner	Execute Python code	Python, RestrictedPython, uv
Alpine Image	Development/self-hosted	Alpine Linux, includes shell/package managers
Distroless Image	Production/cloud	Google Distroless, hardened, no shell

Key Features:

• Process-level isolation from main n8n application
• Sandboxed code execution with restricted APIs
• Configurable library whitelists for security
• Multi-architecture support (AMD64, ARM64)
• Health monitoring and auto-recovery
• Extensible for custom package requirements

The system balances security, performance, and flexibility, allowing users to execute custom code safely while maintaining the stability of the main n8n application.

Sources: docker/images/runners/Dockerfile docker/images/runners/Dockerfile.distroless docker/images/runners/n8n-task-runners.json