Sandboxing

Users can write code in n8n in three places:

• Expressions
• Code nodes
• Custom tools of agents

n8n runs arbitrary code in these sandboxes:

• V8 isolates for expressions on the backend, and for custom tools of agents
• QuickJS, for expressions in the frontend (in rollout)
• Task runners for Code nodes
• Remote sandboxes for code that the n8n Assistant writes

This page explains how each sandbox protects the n8n process from this code.

Expressions

By default, n8n runs each expression in a V8 isolate, i.e. a separate JavaScript heap with its own memory limit. The legacy engine used to run expressions inside the n8n process.

The frontend still evaluates expressions with the legacy engine, but is moving to QuickJS. An expression can therefore give one result in the frontend and another on the backend.

Code node

A Code node runs JavaScript or Python in a task runner, i.e. a separate process next to the main in regular mode, or next to the worker in queue mode.

By default (N8N_RUNNERS_MODE=internal), the runner is a child process of n8n in the same container. It gets only a set of allowed environment variables, but it shares the files and the OS user of n8n. In external mode, the runner is in a sidecar container, so the code cannot reach the memory, environment variables, or files of n8n. In both modes, if the code crashes or goes over the heap limit of the runner, only the runner fails. In internal mode, the runner and n8n share the memory limit of the container. If the container runs out of memory, the system can stop n8n too.

Custom tools

For questions on this topic, ask Robin

A custom tool is a function that a user writes for an agent to call. The agents module runs each custom tool in a pool of V8 isolates.

Unlike a task runner, an isolate runs inside the n8n process. If a custom tool runs out of memory, n8n discards its isolate, and the main keeps running.

n8n Assistant

For questions on this topic, ask Jaakko

The n8n Assistant writes the source code of a workflow, and compiles it in a remote sandbox, so that its file writes and commands do not run on the n8n host. Without a sandbox, the Assistant cannot build workflows.

Quiz

1. A user sees one value in the expression preview, and the backend gives another value. What is a likely cause?
   • The frontend evaluates with the legacy engine, and the backend runs the expression in an isolate.
   • The frontend caches old run data.
   • The task runner changes the value.
   • The database rounds the value.
2. In queue mode, where does a Code node run?
   • In a task runner next to the main.
   • In the isolate pool of the main.
   • In a task runner next to the worker.
   • Inside the worker process.
3. Where does a custom tool of an agent run?
   • In a task runner.
   • In an isolate of the agents module.
   • In the remote sandbox of the n8n Assistant.
   • In a separate container.