n8n Task Runner Launcher Simplify Automation Setup

The n8n Task Runner Launcher is a dedicated binary that isolates scripting environments from the core n8n application. It acts as an intermediary to execute Python or JavaScript code in separate processes, preventing resource spikes or script errors from crashing your main instance or workers.

Prerequisites: An active n8n instance (Docker preferred) and basic terminal access.

Inspection Step:
Verify the launcher binary by downloading from releases:

wget -O task-runner-launcher https://github.com/n8n-io/task-runner-launcher/releases/latest/download/task-runner-launcher-linux-amd64.tar.gz
tar -xzf task-runner-launcher-linux-amd64.tar.gz
tchmod +x task-runner-launcher
./task-runner-launcher --help

Common Failures:

• Command not found: Ensure you downloaded the correct architecture (amd64/arm64).
• No output: Check file permissions with ls -la task-runner-launcher.

Deploy the launcher as a sidecar container to your n8n instance. Create config file at /etc/n8n-task-runners.json (or set N8N_RUNNERS_CONFIG_PATH):

1. Configure N8N_RUNNERS_AUTH_TOKEN (required for both launcher and n8n):
2. Run launcher specifying runner types:

   ./task-runner-launcher javascript
   # or multiple:
   ./task-runner-launcher javascript python

3. Configure orchestrator liveness checks on launcher port 5680 (N8N_RUNNERS_LAUNCHER_HEALTH_CHECK_PORT) and broker port 5679 (N8N_RUNNERS_BROKER_PORT).

Verification: curl http://localhost:5680/healthz returns HTTP 200.

Common Failures: Auth token mismatch or blocked ports 5679/5680.

The launcher reads JSON config from /etc/n8n-task-runners.json. Example for JavaScript runner:

[
  {
    "runner-type": "javascript",
    "workdir": "/opt/n8n/scripts",
    "command": "node",
    "args": [],
    "health-check-server-port": 5681,
    "allowed-env": ["PATH", "NODE_PATH"],
    "env-overrides": {"LOG_LEVEL": "info"}
  }
]

Key Variables: N8N_RUNNERS_AUTH_TOKEN (required). Use _FILE suffix for secrets. Launcher auto-passes N8N_RUNNERS_TASK_BROKER_URI, N8N_RUNNERS_GRANT_TOKEN.

Verification: Launcher logs show loaded config on startup.

n8n (ports 5678/5679) connects to launcher (5680) which manages runners (5681+). Kubernetes probes both n8n and launcher health endpoints while launcher monitors runner health.

Get broker URL from n8n Settings > Task Runners. Runners show “Online” status when healthy.

Common Failures:

• Network blocks on ports 5679/5680/5681
• Mismatched N8N_RUNNERS_AUTH_TOKEN
• Runner health check fails (verify unique ports for multiple runners)

Ensure launcher runs persistently. Verify health endpoints remain responsive under load.

Monitor startup logs for config loading and runner connections.

Final Check:

curl http://localhost:5680/healthz
curl http://localhost:5679/healthz

Both return HTTP 200 for healthy deployment.

Quick Setup: Download and run the automated setup.sh script: setup.sh (Co-authored by ).