Isolated Task Runners
Relevant source files
The following files were used as context for generating this wiki page:
Isolated Task Runners represent the architectural layer in n8n responsible for executing workflow logic, particularly code and node operations, within secure and distinct environments. This isolation ensures that triggers, custom code, and data processing tasks do not interfere with the core application's stability or security. Within the n8n ecosystem, isolation is applied at multiple levels: from the "complete isolation" of trigger executions to the "sandboxed environment" used for high-risk operations like custom JavaScript/Python code execution.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:251, packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:175
Execution Isolation Principles
Trigger Isolation
In n8n, each trigger’s execution is designed to run in complete isolation. This means that if a workflow is triggered by multiple sources (e.g., a Webhook and a Schedule Trigger), different branches have no effect on each other. This isolation is a fundamental guarantee of the execution engine, ensuring that data from one execution instance cannot leak into another concurrent run.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:251-253
Code Sandbox Isolation
Custom logic implemented via "Code" or "Function" nodes is executed within a restricted, sandboxed environment. This sandbox is specifically designed to prevent unauthorized system access. Key restrictions include:
- No Network Access: Code nodes cannot use
fetch(),axios, or standard HTTP modules (http,https) at runtime. - Restricted Globals: Access to standard Node.js globals is limited to a safe subset.
- Performance Overhead: Because these nodes run in a secure sandbox, they are inherently slower than native n8n nodes.
Sources: packages/@n8n/instance-ai/skills/workflow-builder/SKILL.md:175-178
Task Runner Architecture
The architecture distinguishes between native node execution and isolated code execution. Native nodes use internal helpers for operations like grouping and aggregating data while maintaining security against prototype pollution.
Node Execution Flow
Native nodes follow a structured lifecycle consisting of execute, poll, trigger, or webhook methods. These run within the n8n process but utilize safety utilities (e.g., isSafeObjectProperty) to prevent untrusted user input from manipulating the application's runtime.
Sources: packages/nodes-base/AGENTS.md:5-12, packages/nodes-base/AGENTS.md:73-82
Workflow Traversal Logic
The system utilizes graph traversal utilities to manage the flow between isolated tasks. Connections are indexed by source nodes, and parent nodes are identified by inverting these connections.
This diagram illustrates the progression from a trigger to various nodes while maintaining path isolation during branching.
Sources: AGENTS.md:162-171
Resource and Memory Management
Isolated runners must manage resources efficiently to prevent memory issues, especially when processing large datasets. The "Split In Batches" node is a critical component here, allowing tasks to be processed in chunks (e.g., 100 items at a time) rather than all at once.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:16, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:127-130
Memory Safeguards
| Mechanism | Purpose | Recommended Threshold |
|---|---|---|
| Batching | Prevent memory overload | 100+ items |
executeOnce | Prevent redundant executions on independent sources | N/A |
| Data Pinning | Save API costs and speed development | Testing phase |
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:127-130, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:65
Testing Isolation
The project employs rigorous isolation for its testing runners (Playwright). Each test utilizes unique identifiers (via nanoid) and isolated browser contexts to prevent session bleeding.
Test Isolation Strategies
- Worker Isolation: Tests can be configured to use a fresh database per worker by setting
TEST_ISOLATIONenvironment variables. - Context Isolation: UI tests requiring multiple users leverage isolated browser contexts (e.g.,
n8n.start.withUser(member)). - Database Resets: The
@db:resettag can be used on test descriptions to ensure a clean state between executions.
Sources: packages/testing/playwright/AGENTS.md:105-117, packages/testing/playwright/AGENTS.md:154-156
This sequence diagram shows how the test runner manages separate browser contexts and database states to ensure test isolation.
Sources: packages/testing/playwright/AGENTS.md:120-131
Conclusion
Isolated Task Runners in n8n provide a multi-layered security and stability framework. By sandboxing custom code, ensuring trigger isolation, and providing tools like batching for memory management, n8n maintains high performance without compromising the integrity of the core workflow engine. This architecture is mirrored in the testing infrastructure, where isolated workers and contexts ensure reliable, parallelized verification.