N8N Task Runners: Python & JavaScript Code Veilig Uitvoeren in Isolated Environments (2025)

🚀 Samenvatting

N8N Task Runners zijn een revolutionaire feature (sinds v1.111.0) die Python en JavaScript code uitvoert in volledig geïsoleerde Docker containers. Dit betekent 100% veilige code execution, geen memory leaks, betere performance en de mogelijkheid om externe npm/pip packages te gebruiken zonder je hoofdinstallatie te vervuilen. In deze gids leer je alles over setup, configuratie en best practices.

Wat zijn N8N Task Runners?

Task Runners zijn een nieuwe architectuur in N8N die code execution volledig isoleert van de hoofdapplicatie. In plaats van code direct in het N8N proces uit te voeren, worden speciale containers gebruikt die als 'sandbox' fungeren.

🏗️ Task Runner Architectuur

Componenten:

• Task Requester: N8N hoofdproces dat code execution aanvraagt
• Task Broker: Beheert communicatie tussen requester en runners
• Task Runners: Geïsoleerde containers die daadwerkelijk code uitvoeren

Workflow:

1. Code node stuurt execution request naar broker
2. Broker wijst task toe aan beschikbare runner
3. Runner voert code uit in isolated environment
4. Resultaat wordt teruggestuurd via broker

Waarom Task Runners Gebruiken?

Task Runners lossen fundamentele problemen op die traditionele code execution heeft:

❌ Zonder Task Runners

• Code draait in hoofdproces (security risk)
• Memory leaks beïnvloeden hele N8N
• NPM packages global installeren
• Geen resource limits mogelijk
• Crash kan N8N stoppen
• Beperkte Python support

✅ Met Task Runners

• Volledig geïsoleerde execution
• Auto-cleanup na elke run
• Packages per runner installeren
• CPU/Memory limits instelbaar
• Crash beïnvloedt N8N niet
• Native Python execution

⚡ Performance Voordelen

Task Runners verbeteren performance significant:

• Parallel execution: Meerdere runners draaien tegelijkertijd
• No blocking: Hoofdproces blijft responsive
• Auto-scaling: Runners schalen met workload
• Memory efficiency: Elke runner heeft eigen memory pool

Internal vs External Mode

N8N Task Runners kunnen in twee modes draaien. De keuze bepaalt hoe runners worden beheerd:

Aspect	Internal Mode	External Mode
Setup Complexity	Simpel - automatisch	Complex - manual containers
Production Ready	❌ Niet aanbevolen	✅ Aanbevolen
Isolation Level	Beperkt	Volledig
Resource Control	Minimaal	Volledig configureerbaar
Scaling	Auto (beperkt)	Manual (onbeperkt)
Use Case	Development/Testing	Production

Docker Setup & Configuratie

Voor production gebruik raden we External Mode aan met Docker Compose. Hier is een complete setup:

📄 docker-compose.yml

version: '3.8'

services:
  # PostgreSQL Database
  postgres:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: n8n
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - n8n-network

  # N8N Main Application
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
      - "5679:5679"  # Task Broker Port
    environment:
      # Database Configuration
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: n8n
      
      # Task Runners Configuration
      N8N_RUNNERS_ENABLED: "true"
      N8N_RUNNERS_MODE: "external"
      N8N_RUNNERS_AUTH_TOKEN: "my-super-secret-auth-token-change-this"
      N8N_RUNNERS_BROKER_PORT: 5679
      N8N_RUNNERS_BROKER_ADDRESS: "0.0.0.0"
      
      # Python Runner Support
      N8N_NATIVE_PYTHON_RUNNER: "true"
      
      # Performance Settings
      N8N_RUNNERS_MAX_PAYLOAD_SIZE: 16777216  # 16MB
      N8N_RUNNERS_MAX_CONCURRENCY: 10
      N8N_RUNNERS_TASK_TIMEOUT: 60  # seconds
      N8N_RUNNERS_HEARTBEAT_INTERVAL: 30  # seconds
      
      # General N8N Settings
      GENERIC_TIMEZONE: Europe/Amsterdam
      N8N_HOST: localhost
      N8N_PROTOCOL: http
      N8N_DEFAULT_BINARY_DATA_MODE: filesystem
      EXECUTIONS_DATA_SAVE_ON_ERROR: all
      EXECUTIONS_DATA_SAVE_ON_SUCCESS: all
    volumes:
      - n8n_data:/home/node/.n8n
      - ./files:/files
    networks:
      - n8n-network
    depends_on:
      - postgres

  # JavaScript Task Runner
  n8n-runner-js:
    image: n8nio/runners:latest
    restart: unless-stopped
    environment:
      N8N_RUNNERS_MODE: "external"
      N8N_RUNNERS_AUTH_TOKEN: "my-super-secret-auth-token-change-this"
      N8N_RUNNERS_BROKER_HOST: "n8n"
      N8N_RUNNERS_BROKER_PORT: 5679
      N8N_RUNNERS_MAX_CONCURRENCY: 5
      N8N_RUNNERS_TASK_TIMEOUT: 60
      NODE_OPTIONS: "--max-old-space-size=2048"  # 2GB memory limit
    networks:
      - n8n-network
    depends_on:
      - n8n

  # Python Task Runner
  n8n-runner-python:
    image: n8nio/runners:latest
    restart: unless-stopped
    environment:
      N8N_RUNNERS_MODE: "external"
      N8N_RUNNERS_AUTH_TOKEN: "my-super-secret-auth-token-change-this"
      N8N_RUNNERS_BROKER_HOST: "n8n"
      N8N_RUNNERS_BROKER_PORT: 5679
      N8N_RUNNERS_MAX_CONCURRENCY: 5
      N8N_RUNNERS_TASK_TIMEOUT: 60
      RUNNER_TYPE: "python"  # Specify Python runner
    volumes:
      - ./python-requirements.txt:/requirements.txt:ro
    networks:
      - n8n-network
    depends_on:
      - n8n

volumes:
  postgres_data:
  n8n_data:

networks:
  n8n-network:
    driver: bridge

🚀 Deployment Stappen

Create docker-compose.yml:

nano docker-compose.yml

Start services:

docker-compose up -d

Check logs:

docker-compose logs -f n8n-runner-js

Test in N8N: Open http://localhost:5678 en test een Code node

Python Task Runner Activeren

Python support in N8N Task Runners opent een wereld aan mogelijkheden met data science libraries:

🐍 Python Configuration

Environment Variables:

# In je docker-compose.yml of .env file
N8N_NATIVE_PYTHON_RUNNER=true
RUNNER_TYPE=python

Custom Python Packages:

Maak een requirements.txt:

# Data Science
pandas==2.1.4
numpy==1.24.3
scipy==1.11.4
scikit-learn==1.3.2

# API & Web
requests==2.31.0
beautifulsoup4==4.12.2

# Database
psycopg2-binary==2.9.9
sqlalchemy==2.0.23

# Utils
python-dotenv==1.0.0
pydantic==2.5.2

📝 Python Code Node Voorbeeld

import pandas as pd
import numpy as np
from datetime import datetime, timedelta

# Access input data from previous node
input_data = $input.all()

# Process data with pandas
df = pd.DataFrame(input_data)

# Data transformations
df['processed_date'] = pd.to_datetime(df['date'])
df['days_ago'] = (datetime.now() - df['processed_date']).dt.days

# Aggregations
summary = {
    'total_records': len(df),
    'average_value': df['value'].mean(),
    'max_value': df['value'].max(),
    'unique_users': df['user_id'].nunique()
}

# Machine Learning example
from sklearn.linear_model import LinearRegression

X = df[['days_ago']].values
y = df['value'].values

model = LinearRegression()
model.fit(X, y)

# Predict next week
next_week = np.array([[-7]])
prediction = model.predict(next_week)[0]

summary['predicted_value_next_week'] = float(prediction)

# Return results
return [summary]

JavaScript Task Runner Setup

JavaScript runners zijn standaard geconfigureerd, maar je kunt ze optimaliseren voor specifieke use cases:

⚙️ JavaScript Runner Optimalisaties

Memory Settings:

# Increase memory limit
NODE_OPTIONS="--max-old-space-size=4096"

# Enable memory profiling
NODE_OPTIONS="--expose-gc --trace-gc"

Performance Flags:

# Optimize for speed
NODE_OPTIONS="--turbo --ignition"

# JIT compilation
NODE_OPTIONS="--opt --no-lazy"

NPM & Pip Packages Installeren

Een van de grootste voordelen van Task Runners is package management per container:

📦 Custom Docker Image met Packages

Maak een custom runner image met pre-installed packages:

Dockerfile.runner

# Base image
FROM n8nio/runners:latest

# Switch to root for installations
USER root

# Install system dependencies
RUN apk add --no-cache \
    python3-dev \
    gcc \
    musl-dev \
    postgresql-dev

# Install Python packages
COPY requirements.txt /tmp/
RUN pip3 install --no-cache-dir -r /tmp/requirements.txt

# Install Node packages globally
RUN npm install -g \
    axios@1.6.2 \
    cheerio@1.0.0-rc.12 \
    moment@2.29.4 \
    lodash@4.17.21 \
    uuid@9.0.1 \
    crypto-js@4.2.0

# Install specific Node packages in workspace
WORKDIR /workspace
COPY package.json .
RUN npm install

# Switch back to node user
USER node

WORKDIR /home/node

💡 Pro Tip: Volume Mount voor Development

Voor development kun je packages dynamisch laden via volumes:

services:
  n8n-runner-js:
    volumes:
      - ./node_modules:/home/node/node_modules:ro
      - ./custom-packages:/home/node/custom:ro

Security & Resource Limits

Task Runners bieden enterprise-grade security features voor veilige code execution:

🔒 Security Configuration

Authentication:

# Strong authentication token (gebruik een random 64-char string)
N8N_RUNNERS_AUTH_TOKEN="$(openssl rand -hex 32)"

# TLS encryption voor broker communication
N8N_RUNNERS_TLS_ENABLED="true"
N8N_RUNNERS_TLS_CERT="/path/to/cert.pem"
N8N_RUNNERS_TLS_KEY="/path/to/key.pem"

Resource Limits:

# Docker Compose resource limits
services:
  n8n-runner-js:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M
    ulimits:
      nproc: 100
      nofile:
        soft: 1024
        hard: 2048

Network Isolation:

# Isolated network zonder internet access
networks:
  runner-network:
    driver: bridge
    internal: true  # No external access
    
services:
  n8n-runner-js:
    networks:
      - runner-network
    dns:
      - 1.1.1.1  # Alleen als external access nodig is

⚡ Environment Variables Reference

Variable	Default	Description
N8N_RUNNERS_TASK_TIMEOUT	60	Max execution time in seconds
N8N_RUNNERS_MAX_PAYLOAD_SIZE	16777216	Max data size (16MB default)
N8N_RUNNERS_MAX_CONCURRENCY	5	Concurrent tasks per runner
N8N_RUNNERS_HEARTBEAT_INTERVAL	30	Health check interval
N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT	300	Idle shutdown time

Troubleshooting & Common Issues

Hier zijn oplossingen voor de meest voorkomende problemen met Task Runners:

❌ Error: "Code generation from strings disallowed"

Oorzaak: Task Runners ondersteunen geen dynamische code generation

Oplossing:

• Gebruik geen eval() of Function() constructors
• Replace Handlebars templates met native JavaScript
• Use static functions in plaats van string-based code

❌ Error: "Cannot find module 'axios'"

Oorzaak: NPM packages niet geïnstalleerd in runner container

Oplossing:

# Build custom image met packages
docker build -f Dockerfile.runner -t my-n8n-runner .

# Update docker-compose.yml
image: my-n8n-runner:latest

❌ Error: "Task runner connection failed"

Checklist:

✓ Broker port 5679 is open
✓ AUTH_TOKEN matches in all containers
✓ Containers in same network
✓ Firewall rules allow traffic

# Debug connection
docker exec n8n-runner-js nc -zv n8n 5679

❌ Error: "Task timeout exceeded"

Oorzaak: Code execution duurt langer dan timeout

Oplossing:

# Increase timeout to 5 minutes
N8N_RUNNERS_TASK_TIMEOUT=300

Best Practices & Performance Tips

Volg deze best practices voor optimale Task Runner performance:

🚀 Performance Optimalisaties

Runner Scaling:

• Start met 2-3 runners per type
• Monitor CPU/Memory usage
• Scale horizontal bij >80% usage
• Use auto-scaling in Kubernetes

Code Optimization:

• Minimize data transfers
• Use streaming voor large datasets
• Cache repeated calculations
• Batch process waar mogelijk

Resource Management:

• Set appropriate memory limits
• Use CPU limits voor fairness
• Configure swap voor safety
• Monitor disk I/O

Security Hardening:

• Rotate AUTH tokens regularly
• Enable TLS voor production
• Use read-only volume mounts
• Implement network policies

⚠️ Common Pitfalls te Vermijden

• Global state: Runners delen geen state - gebruik database/cache
• File system access: Containers hebben isolated filesystems
• Network calls: Configure firewall rules voor external APIs
• Large payloads: Split data >10MB in chunks
• Infinite loops: Altijd exit conditions toevoegen

Geavanceerde Use Cases

Task Runners maken complexe automatisering mogelijk die voorheen onmogelijk was:

🤖 Machine Learning Pipeline

• Train models met scikit-learn
• Process data met pandas
• Generate predictions real-time
• A/B test model versions

📊 Data Processing

• ETL pipelines met Python
• PDF/Excel processing
• Image manipulation
• Video transcoding

🔗 Blockchain Integration

• Smart contract interaction
• Wallet management
• Transaction monitoring
• DeFi automation

🧪 Testing & QA

• Automated testing suites
• Performance benchmarking
• Security scanning
• Code quality checks

🎯 Klaar om Task Runners te Implementeren?

Task Runners transformeren N8N in een enterprise-ready automation platform. Start vandaag met veilige, schaalbare code execution!

N8N Installatie Service (€100) Docker Setup Guide →

Conclusie

N8N Task Runners zijn een game-changer voor workflow automatisering. Door code execution te isoleren in containers, krijg je enterprise-grade security, betere performance en onbeperkte mogelijkheden met externe packages.

Of je nu Python data science pipelines bouwt, complexe JavaScript transformaties uitvoert, of machine learning models deployed - Task Runners maken het mogelijk, veilig en schaalbaar.

📚 Verder Lezen

• N8N Code Node Guide - Basis code execution
• N8N Security Best Practices - Beveiligingsrichtlijnen
• N8N Self-Hosted Guide - Complete hosting setup

Heb je vragen over Task Runners of hulp nodig met de setup? Contact me voor persoonlijke ondersteuning!

#n8n #task runners #python #javascript #docker #security #sandboxing #code execution