The Complete n8n Guide: Install, Build AI Agents, Scale, and Secure Your Instance

Introduction

n8n is a node-based workflow automation platform that you can run on n8n’s cloud or on your own server, and it has become a popular choice for teams that want automation and AI agents without per-task pricing. This guide is the map of everything we have published about n8n on ToolPilot: 62 hands-on tutorials organized into the order you will actually need them, from your first install to queue mode scaling and emergency patching. New readers should follow the sections in order. Experienced users can jump straight to the section that matches the problem in front of them.

Quick answer

n8n is worth using if you want workflow automation you control: it is free to self-host under the Sustainable Use License, connects hundreds of services through prebuilt nodes, and includes a native AI Agent node for LLM-powered workflows. Start with Docker Compose, build one agent, then scale with PostgreSQL and queue mode.

Evidence

The case for n8n starts with its community. The n8n repository on GitHub counted 208,133 stars and 61,194 forks as of October 21, 2026, which makes it one of the most watched automation projects in the world and means most problems you hit have already been solved in public. The database story points the same direction. In the Stack Overflow 2025 Developer Survey, PostgreSQL was the most used database at 55.6% of respondents, and PostgreSQL is the database n8n itself recommends for production, so the skills you build here transfer to the rest of your stack.

The official n8n Docker Compose install guide gives the clearest verdict on where a trial install should end up: “SQLite is fine for trying things out, but for a production instance that must handle more than a handful of users or workflows running around the clock use Postgres instead.” The same documentation set explains the AI side of the platform: the advanced AI tutorial walks through building agents on n8n’s LangChain-based nodes, which is the foundation every agent tutorial in this guide builds on. Treat those two pages as the canonical references behind this guide; everything below is the hands-on layer on top of them.

Getting started and deployment

Install n8n once, the boring way, and every later tutorial in this guide gets easier. Our default stack is Docker Compose on an Ubuntu VPS with PostgreSQL and a reverse proxy that provides HTTPS, because that combination survives upgrades, restarts, and real traffic. The npm install still works for a quick local trial, but it is a dead end for production: n8n 3.0 drops npm support entirely, so anything you plan to keep should start on Docker.

Two habits matter more than the install command itself. First, pin the version you deploy and upgrade on a schedule you control, reading the release notes before you pull a new image. Second, protect your data directory and its encryption key from the first day, because losing the key means losing every stored credential with it. If you inherit an older npm install, migrate it to Docker before you do anything else, and if your instance still runs on SQLite, plan the move to PostgreSQL before the workflow count grows.

• Install n8n on an Ubuntu VPS: the full first install, with Docker Compose, Postgres 18, and free HTTPS via Caddy.
• n8n Docker Compose setup: a production compose file with Postgres, Redis queue mode, backups, and safe upgrades.
• Migrate n8n from npm to Docker: move a legacy npm install onto Docker before 3.0 removes npm support.
• How to update n8n self-hosted: safe upgrade paths for Compose, Docker, and npm, with rollback steps.
• n8n 3.0 upgrade guide: the breaking changes checklist, covering Docker-only deployment, removed nodes, and new security defaults.

Building AI agents

n8n’s AI Agent node turns a workflow into a reasoning loop: a chat model decides which tools to call, reads the results, and answers in plain language. Build your first agent small, with one channel and two or three tools, and only add memory, sub-agents, and extra channels once the basic loop is reliable. The Agent Builder shortens that first build by generating an agent scaffold from a description, which you then refine by hand.

The failures in this section are the ones every agent builder meets. Agents ignore their tools when tool descriptions are vague, so write descriptions like instructions to a colleague. Agents repeat side effects when several executions race, so give concurrent agents an atomic claiming pattern before they touch shared data such as calendars or inboxes. Chat memory is the difference between a demo and an assistant, and it belongs in PostgreSQL once the bot serves real users. Local models through Ollama work well for private or offline agents, as long as the model you pick actually supports tool calling.

• n8n Agents tutorial: build a Telegram AI agent from scratch with tools, skills, and schedules.
• n8n AI Agent tutorial: build your first AI agent with a chat model, tools, and memory, tested on n8n 2.40.7.
• Build agents with the n8n Agent Builder: define an agent, attach workflows as tools, and gate risky actions with human approval.
• Create n8n Agent Skills: write SKILL.md files that teach coding agents to generate correct n8n workflows.
• Multi-agent workflows with sub-agents: parent orchestrators that delegate work to nested sub-agent workflows.
• Message an Agent node: call published agents from other workflows and reuse their sessions.
• WhatsApp channel for n8n agents: connect a WhatsApp Business number to an agent through the Cloud API.
• Ollama with the n8n AI Agent: run local LLMs as agent models, with tool-calling fixes and a fallback model.
• Build an AI support chatbot: a support bot with a RAG knowledge base, memory, and human escalation.
• n8n chatbot memory: give a chatbot conversation memory, scoped per user.
• Fix an agent that is not calling tools: four proven fixes for agents that ignore the tools you attached.
• AI agent race conditions: three atomic claiming patterns that stop concurrent agents double-booking.
• n8n AI agent production reliability checklist: guardrails for silent tool failures, timeout cascades, output drift, and runaway loops before an agent goes live.

RAG and data

Retrieval-augmented generation is the pattern behind most useful n8n AI projects: split your documents into chunks, embed them into a vector store, and let the agent retrieve the relevant chunks before it answers. The quality of the answer depends mostly on chunking and on matching your embedding model’s dimensions to the store, not on the size of the chat model. Qdrant is our default self-hosted store and Pinecone is the managed option, and the same Vector Store node drives both.

Data discipline matters just as much underneath the AI layer. PostgreSQL plays three roles in a mature n8n setup: it is the database n8n itself runs on, the memory store for production chatbots, and a general automation target you can query from any workflow. If your instance still runs on SQLite, migrate before you build RAG on top of it, because the migration gets slower and riskier as executions pile up.

• LangChain RAG tutorial: build a chatbot that answers from your documents with Qdrant and the Question and Answer Chain.
• n8n Vector Store tutorial: insert and retrieve embeddings with Pinecone and Qdrant.
• n8n Postgres tutorial: connect, query, insert, and update PostgreSQL from n8n workflows.
• Migrate n8n from SQLite to PostgreSQL: move n8n’s own database with the export and import CLI, without losing workflows.

Integrations and migrations

n8n earns its place in a stack by connecting things, and the Model Context Protocol has become the most important connection of all. n8n works on both sides of MCP: it can expose your workflows as tools that Claude Code and other MCP clients call directly, and its agents can consume tools from external MCP servers. That two-way support is why n8n increasingly sits in the middle of AI tooling instead of at the edge.

Migrations follow a repeatable pattern. Inventory what the old platform actually runs, map each trigger and action to n8n nodes, rebuild the highest-volume workflow first, and run both systems in parallel until the numbers match. The Zapier migration guide works through a real example, and the Make comparison settles the platform choice for agent workloads before you commit. Specialist nodes cover the long tail, from Microsoft Dataverse business data to programmatic PDF processing with pdfRest. Finally, most “my webhook stopped working” reports trace back to one missing environment variable behind a reverse proxy, and the fix takes five minutes once you know where to look.

• n8n workflows as MCP tools in Claude Code: expose workflows through n8n’s MCP server and run them from the terminal.
• Migrate from Zapier to n8n: export Zaps, map them to nodes, and rebuild a real workflow end to end.
• Migrate the n8n Perplexity node to v3: Sonar Chat retired on 2026-09-27, so map fields to the v3 Agent API with preset equivalents and a rollback-safe plan.
• Migrate the n8n Notion node to v3: swap database IDs for data source IDs, fix every operation and the trigger, and test safely.
• n8n vs Make for AI agents: a head-to-head comparison with pricing math and model freedom.
• Microsoft Dataverse node: automate Dynamics 365 data with all six row operations and OData queries.
• pdfRest PDF automation: OCR, permanent redaction, and ZUGFeRD e-invoicing from n8n.
• Generate images with Gemini Nano Banana: build a workflow that generates product and social images with Gemini Nano Banana 2.1, including cost math and retries.
• Fix “Webhook Not Registered” 404s: set N8N_WEBHOOK_URL correctly behind Nginx or another proxy.

Security and patching

Self-hosting trades a subscription bill for a responsibility: when n8n publishes a security fix, nobody applies it for you. The year 2026 made that concrete. The Ni8mare vulnerability (CVE-2026-21858) scored a perfect CVSS 10.0 and allowed unauthenticated remote code execution through webhooks, and CVE-2026-44791 scored CVSS 9.4 in the XML node. Monthly security bulletins have become routine, and several September advisories shipped without CVE IDs at all, which means vulnerability scanners that key on CVE numbers simply never flagged them.

Build a patching routine instead of reacting to headlines. Watch the official advisories, test each upgrade on a copy of your instance, patch production within days for critical fixes, and rotate credentials after any remote-code-execution fix, because a patched server can still hold stolen keys. Restrict who can reach the editor, keep the instance behind HTTPS, and treat every tutorial in this section as a drill you run before the next bulletin lands, not after.

• Ni8mare (CVE-2026-21858) patch guide: fix the CVSS 10.0 webhook RCE and rotate exposed credentials.
• October 2026 security bulletin: map each release line to its patch version and upgrade safely.
• September 2026 advisories checklist: the three advisory batches scanners missed, with their patch versions.
• CVE-2026-44791 patch guide: fix the XML node prototype pollution bypass or disable the node entirely.
• n8n API key variable scopes: give an API key only the variable scopes it needs, test variable list and create calls with curl, and fix 403 scope errors fast.
• n8n external secrets: connect HashiCorp Vault and AWS Secrets Manager with $secrets expressions and per-project vault scoping.
• Harden self-hosted n8n for teams: patch to 2.44.1, scope credentials by project, and lock nodes after the October 2026 advisories.

Operations and troubleshooting

Production n8n is mostly plumbing. Queue mode is the scaling step: one main instance accepts work, Redis queues it, and worker processes execute in parallel, exactly the architecture the official n8n scaling documentation describes. Queue mode requires PostgreSQL, which is why the database migration appears so early in this guide. In n8n 3.0, Code nodes move to external task runners, a separate sidecar that isolates code execution and lets you control which JavaScript and Python libraries workflows may use.

Reliability work is less glamorous and more valuable. Give every important workflow an error path, use retries with idempotency keys so a retried payment call cannot charge a customer twice, and consider durable execution when a crashed run must resume instead of restart. The troubleshooting guides cover the failures self-hosters actually report: the “Connection lost” banner behind NGINX is a WebSocket proxying problem, “Database not ready” is usually SQLite bloat, and most post-update breakage comes from a short list of causes that includes renamed variables and removed nodes.

• Queue mode scaling: run a main instance plus Redis-backed workers for parallel executions.
• n8n OpenTelemetry tracing: send workflow and node spans to Jaeger or Grafana to find slow nodes.
• n8n S3 binary data storage: move binary data off RAM and disk into Amazon S3, with S3-compatible R2 config, queue-mode worker sync, lifecycle pruning, and the 2.6.4 region fix.
• External task runners in Docker: set up the runners sidecar that n8n 3.0 requires for Code nodes.
• Fix “Connection lost” behind NGINX: WebSocket passthrough, proxy buffering, and hop settings that end the banner.
• Fix n8n Gmail Trigger ETIMEDOUT: a broken IPv6 route is the usual cause, so diagnose and fix it with NODE_OPTIONS=--dns-result-order=ipv4first.
• Fix “Database Not Ready”: diagnose SQLite bloat, run VACUUM safely, and tune execution pruning.
• Code node timeout after 3.0: the timeout dropped from 300 to 60 seconds; restore it or restructure the workflow.
• Fix deprecated nodes before 3.0: find every deprecated node and replace it before the upgrade blocks you.
• Workflows broke after an update: the six real causes, from failed migrations to lost encryption keys.
• How to downgrade n8n in Docker: revert database migrations with n8n db:revert on the current version first, then pin the older image tag and restart the stack.
• n8n error handling: retries, per-node error outputs, and a global Error Trigger workflow.
• n8n error workflow blind spots: four failures an error workflow cannot catch, and how to fix them.
• n8n error workflow blind spots: four failures an error workflow cannot catch, and how to fix them.
• Retry on Fail and idempotency keys: stop retried API calls from charging customers twice.
• n8n publish guardrails: stop broken workflows before they go live with unconnected-input checks and CLI policies.
• Durable execution with Dapr: checkpoint every node so crashed workflows resume where they stopped.
• Telegram Trigger not working: a six-step diagnostic checklist, starting with getWebhookInfo.
• Fix Wait node resume URL 401: why the webhook-waiting signature is required and how to forward the resume URL intact.
• Fix 429 rate limit errors: stagger Schedule Triggers off the hour, add jitter, and treat 429 as an expected retry, not a crash.
• Fix n8n Schedule Trigger firing at the wrong time in Docker: fix Docker timezone bugs by setting node Timezone, workflow timezone, and GENERIC_TIMEZONE in the right order.
• Fix out-of-memory crashes with batch processing: diagnose workflows dying after hours with no node error, then fix them with batching, execution pruning, and heap caps.
• Fix n8n Dataverse node 401 and 403 errors: decode Entra AADSTS codes, repair client secrets, grant admin consent, and assign Dataverse security roles.

Code node and power features

The Code node is where n8n stops being a no-code tool and becomes a development platform. One Code node with the right run mode replaces a chain of utility nodes, and it is the natural home for data transforms that expressions make awkward: reshaping nested JSON, merging items, and computing values across a whole batch. Learn the two run modes, the $input helpers, and the { json } return format, and most workflow logic becomes straightforward. Debugging is fast once you know how the editor surfaces console output from a run.

The Assistant covers the opposite end of the skill range. Describe the workflow you want in plain language, review the plan it proposes, and connect your credentials yourself rather than pasting secrets into a prompt. Our verdict: use the Assistant to draft, the visual editor to refine, and the Code node when the logic outgrows both.

• Code node JavaScript: run modes, $input.all(), data transforms, and debugging, with real errors and fixes.
• Fix Code node $env blocked: restore environment variable access safely with N8N_BLOCK_ENV_ACCESS_IN_NODE and allowlist alternatives.
• n8n Assistant workflow builder: build workflows from a plain-language spec and review the plan before publishing.

FAQ

Is n8n free to use? Self-hosted n8n is free under the Sustainable Use License, which covers running n8n for your own business and internal automation, so your only cost is the server it runs on. n8n Cloud is a paid subscription, and a small set of enterprise features requires a paid license on either deployment type.

Should I choose n8n Cloud or self-hosting? Self-hosting is usually cheaper at volume because executions are not metered, and a small VPS handles thousands of runs a month. Cloud is the better choice when nobody on the team wants to own updates, backups, TLS certificates, and security patches. The real trade-off is operations time, not the subscription price.

How does n8n compare with Zapier and Make? Zapier and Make are fully hosted and charge per task or per operation, which makes them effortless to start and expensive to scale. n8n can be self-hosted for a flat server cost, gives you a Code node and local AI models, and keeps your data on your own machines. Our n8n vs Make comparison works through the pricing math for agent workloads in detail.

Do I need to know how to code to use n8n? No. Most workflows are built by connecting prebuilt nodes on a visual canvas, and built-in expressions handle everyday data mapping. Coding is optional: the Code node accepts JavaScript when a workflow outgrows the prebuilt nodes, and learning a little of it multiplies what you can automate.

Can n8n scale to production workloads? Yes. Move the database from SQLite to PostgreSQL, switch on queue mode so Redis-backed worker processes share executions, and run Code nodes in external task runners. That is the architecture the official scaling documentation describes, and it handles production traffic comfortably when it is patched and monitored.

Is n8n good for building AI agents? Yes. n8n ships a native AI Agent node built on LangChain, with pluggable chat models, memory sub-nodes, vector stores, and the ability to call any workflow or node as a tool. It also works as both an MCP client and an MCP server, so agents built in n8n can use external tools and external agents can call your workflows.

Conclusion

n8n rewards a specific order of learning: install it properly, automate something small, add an agent, then invest in the database, scaling, and patching work that keeps the whole system trustworthy. If you are starting today, install n8n with the Ubuntu VPS guide, build the Telegram agent from the agents tutorial this week, and add the RAG support chatbot once the basic loop feels boring. Come back to the security section on a schedule, not on a headline. The platform will keep changing, and this guide is updated as our tutorials are, so the path above stays current.

Frequently asked questions