Engineering Guide
How to Install n8n Self-Hosted (2026): One-Line Script, Docker Compose, and Agentic AI Wiring
Self-host n8n free on your own server: the one-line script, Docker Compose, and how to wire AI agents in — Grok on the AI Agent node, outside agents through n8n's MCP server.
Short answer, up top: yes — you can self-host n8n for free on your own server, and yes, you can wire real AI agents into it, either inside n8n (chat models on its AI Agent node) or from outside (agents that drive your instance through n8n's MCP server).
Second thing to know up front: the install methods changed. If you're here to learn how to install n8n on your own hardware, be suspicious of older tutorials — npm installs are deprecated from n8n 3.0 (launching October 2026), and most guides in the wild predate that change.
A word on who's writing: we're a small engineering shop in Puerto Rico; we build AI-agent automation for clients, we run our own agents (our AI-lab prototypes live on this blog), and we've written before about what a developer actually needs to succeed in the age of AI. This guide is the install half of that story, written for a teammate who owns a VPS: current methods first, limits stated plainly.
Before you start: server requirements (or a laptop)
Start at 4 GB of RAM and 2 vCPUs, with Docker installed — that's the whole hardware bar, whether the target is a laptop or a rented VPS.
Where that number comes from: the Docker Compose page carries the only quantified minimum in n8n's current docs — "at least 4 GB of RAM and 2 vCPUs" — and there is no dedicated system-requirements page anymore. The figure isn't padding, either: the sandbox that runs AI-generated code (sandbox-runner-1) uses Docker-in-Docker, and n8n's docs note it needs more headroom than a typical container.
Docker is what n8n recommends for most self-hosting. Linux and macOS are first-class; the one-line script below is POSIX-only, so Windows users go through WSL2 — Git Bash hasn't been verified end-to-end by n8n.
Also bring an API key to install day so the agentic section isn't theoretical: an xAI key for Grok (created on the xAI Console's API Keys page), and/or an Anthropic, OpenAI, or OpenRouter key for the built-in AI Assistant. And a dry line from n8n's own docs: "If you aren't experienced at managing servers, n8n recommends n8n Cloud." Self-hosting buys you control and bills you sysadmin time — budget for both.
Method 1 — how to install n8n in one line (fastest)
If you're asking "how do I get started with n8n", this is the fastest documented path — one shell command on Linux or macOS (Windows goes through WSL2, below):
curl -fsSL https://get.n8n.io | sh Per n8n's one-line setup docs, that command writes a compose.yml and a .env file, runs the stack on a SQLite database, and starts n8n alongside the sandbox services the AI Assistant depends on. You end up with a running instance and an ordinary directory of Compose files you can read — nothing magical, which is the main thing we like about it.
Three details worth flagging:
- It replaces
npm install n8nandnpx n8n, which per the docs no longer work from n8n 3.0 onwards (3.0 launches October 2026). - The one-line page documents an upgrade path for later version moves, so updating doesn't mean hand-patching a running install.
- It's POSIX-only; on native Windows, n8n itself notes the script hasn't been verified under Git Bash — this path assumes WSL2.
One piece of shop honesty: this is still curl | sh — a remote script piped into a shell. It's the documented official command and the fastest route to a working instance, but reading a script before running it on a server you own is a habit worth keeping, and the Compose method below exists for people who want to see every container definition before anything executes. When the script finishes, n8n is listening on port 5678.
Method 2 — Docker Compose (what a real server run uses)
Docker Compose is the install method n8n's docs recommend for a serious self-hosted deployment — the recommended manual production install, "manual" meaning you own the Compose files. If your hunt for an n8n docker install lands on old docker run one-liners, n8n's own Docker page now carries an explicit "this content is outdated" banner and points to Docker Compose instead.
The official configurations live in n8n's n8n-hosting repository — Docker Compose setups for various architectures, including a hardened example wired for Postgres. Start from the repo rather than assembling services by hand; those files encode decisions (ports, volumes, sandbox wiring) that are easy to get subtly wrong from scratch.
What the recommended stack contains, per the Compose docs: the n8n service running on SQLite by default, plus a sandbox stack for the AI Assistant — sandbox certificates, a sandbox API, and a privileged Docker-in-Docker runner (sandbox-runner-1) that executes AI-generated code — alongside a bundled SearXNG instance for web search. The Assistant's optional web search uses that bundled SearXNG or a Brave Search key.
Two things the page states plainly. Sizing: "at least 4 GB of RAM and 2 vCPUs," again because of the Docker-in-Docker sandbox. Security: the page's security checklist tells you to treat that privileged sandbox runner as equivalent to root — fair, since it's a container built to run other containers.
For data that has to survive reboots: SQLite is the default, and the docs direct production installs to Postgres (18), using that hardened withPostgres example — and to follow the PGDATA note in the compose file rather than improvising paths. Database volume paths are exactly the thing you don't want to re-debug at 2 a.m.
What's deprecated — npm, and every pre-2026 tutorial
npm installs are deprecated from n8n 3.0 (launching October 2026) — stated twice by n8n itself: the one-line page notes that npm install n8n and npx n8n no longer work from 3.0 onwards, and the npm install page leads with "npm-based installs are deprecated from n8n 3.0."
If you have to stay pinned on the 2.x line for a while, the npm page still documents that path: Node.js between 20.19 and 24.x inclusive, an install method flagged "not safe for production," the n8n AI Assistant unavailable on npm installs entirely — and even the old npx n8n trial command sits under the same deprecation.
Why a whole section on this: the top forum result ranking for install searches today is a self-hosting guide dated 2021, and most independent tutorials predate the v3.0 change. Follow one, and you hit a wall exactly where the docs have moved. Freshness isn't decoration on this topic — it's the difference between a working install and a broken afternoon.
First boot and set-up checklist
First boot is short: the editor comes up on port 5678 (n8n's documented default), you set the timezone variables n8n's run examples use, and the first-use flow walks you through creating your owner account. We're keeping the UI detail pointer-level: the exact first-run screens aren't consolidated in the pages we cited.
License status: with no license key, n8n runs as the free Community edition — "free with almost the complete feature set," per n8n's own comparison — governed by the Sustainable Use License: free for internal business and non-commercial use under three limitations, with commercial redistribution and Enterprise features moving to the Enterprise License instead.
One pointer we won't improvise: if this instance will receive real production webhooks, it has to be reachable over TLS — a reverse proxy, in practice. The install pages don't consolidate that guidance (it lives elsewhere in the docs), and the old public-tunnel approach is documented as development-only. Plan the proxy into the install.
Wiring agentic AI into your self-hosted n8n
"Agentic," defined for this article: n8n's AI Agent node takes a chat model plus one or more tools, "and the agent decides which tools to call to complete a task." Every agent now runs as the Tools Agent type (selector retired in n8n 1.82.0): model, tools, connect. Background: Anthropic's "building effective agents" (December 2024, so background not spec) is the standard read on agents-direct versus workflows-on-fixed-rails. Three kinds of documented wiring follow.
Grok as the chat model
Add the xAI Grok Chat Model sub-node. It talks straight to the Grok API — api.x.ai/v1, documented as compatible with both the OpenAI and Anthropic SDKs — and the model list loads dynamically from that API. Auth is an API key from the xAI Console's API Keys page. xAI's models page lists grok-4.7 as flagship. Claude comes in through the Anthropic Chat Model sub-node, which adds prompt caching (Disabled / 5 min / 1 hr).
The limitation to state honestly
The built-in AI Assistant is a different surface, and it stays closed to Grok: its provider must be Anthropic, OpenAI, or OpenRouter — no xAI entry — defaulting to anthropic/claude-opus-4-8, sandbox required. Grok does not run your Assistant; Grok runs your AI Agent node. Two different product surfaces, and half the confusion starts with mixing them.
Let outside agents drive your n8n (MCP)
The reverse direction is n8n's built-in MCP server, enabled per workflow: connected clients can search, trigger, build, and edit workflows (build-and-edit from n8n 2.13.0, connect-a-client dialog from 2.33.0). The endpoint is https://<your-n8n-domain>/mcp-server/http, OAuth recommended over API-key auth. Official client recipes exist for Claude Desktop, Claude Code, Codex, Gemini CLI, ChatGPT, Cursor, VS Code, Windsurf, and Lovable; the Claude Code one reads:
claude mcp add --transport http n8n https://<your-n8n-domain>/mcp-server/http MCP is Anthropic's standard, announced November 25, 2024; Claude's API MCP connector can bind the same server directly.
Hermes as the driver agent
Hermes Agent, by Nous Research, is a self-hosted agent — CLI plus desktop — that "lives wherever you put it — a $5 VPS, a GPU cluster, or serverless infrastructure." Install is one line on Linux, macOS, or WSL2:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash Windows gets install.ps1 instead; the installer pins Python, Node.js, npm, ripgrep, FFmpeg; then hermes model, hermes gateway setup. The xAI bridge is first-party: the provider table lists "xAI — Grok models via direct API — set XAI_API_KEY" and "xAI Grok OAuth — SuperGrok/Premium+ subscription, no API key needed." Point it at your n8n MCP server and an outside agent can operate your instance. Stated honestly: no first-party Hermes⇄n8n recipe exists (n8n's client list omits Hermes; Hermes' docs have no n8n guide) — the MCP bridge is the documented path, not a blessed integration. Bot Mode turns profiles into named bots with their own model, memory, and skills; Tier-1 per its docs: macOS, Windows 10/11, Linux/WSL2, Docker — no hermes update inside Docker (update = run a new image).
Grok Bot vs the Grok API
Two products get flattened into "grokbot": the Grok API is the developer API at api.x.ai/v1 — what n8n's Grok node and Hermes' provider connect to. Grok Bot is xAI's agent application — named AI teammates on a persistent cloud computer with a browser, filesystem, and terminal; desktop apps at x.ai/bot; launched August 2026 per xAI's release notes (those doc pages publish under "SpaceX Super Intelligence" branding). Access runs through paid Cursor plans (or Cursor Teams) or a linked SuperGrok subscription — billing detail routes to Cursor's docs, a separate company, so we cite xAI and stop there. Its terminal could execute the documented commands above — xAI's function-calling model is "the model requests the call, you execute it locally" — but no first-party Grok-Bot⇄n8n doc exists and Grok Bot is absent from n8n's MCP client list. That's your own experiment, not a supported integration. Official spelling: "Grok Bot," two words; "Grokbot" isn't an official name.
When to just use n8n's own AI starter kit
The official shortcut deserves its citations: the Self-hosted AI Starter Kit — one Compose template bundling n8n, Ollama, Qdrant, and Postgres — appears at the top of the pages AI answers cite for install prompts, together with its GitHub repo. n8n's own label: "for testing only," "not fully optimized for production environments." Evaluate local-model workflows there in an afternoon; deploy what you have to keep alive from the Compose docs and this guide.
FAQ
Can I run n8n for free?
Yes. Self-hosting runs the free Community edition without a license key, and n8n's own comparison describes it as "free with almost the complete feature set."
Can I self-host n8n?
Yes. The docs pitch it as a first-class deployment path — "You can self-host n8n on your own infrastructure, on-premises, or in a private cloud." You get full deployment control, and n8n's decision guide is upfront that it requires technical expertise.
How can I run n8n locally?
Two documented routes: the one-line setup script (Linux, macOS, or WSL2 on Windows) or Docker Compose. Docker is n8n's recommended engine for most self-hosting — and be careful, because most "n8n docker install" search hits describe the deprecated docker run pattern.
Which AI models can a self-hosted n8n use?
On the AI Agent node: Grok models through the xAI Grok Chat Model sub-node (the model list loads dynamically from the xAI API), and Claude models through the Anthropic Chat Model sub-node. The built-in AI Assistant is a separate surface limited to Anthropic, OpenAI, or OpenRouter keys — no Grok.
Can I install n8n on Windows?
n8n itself installs through WSL2 — the one-line script is POSIX-only, and n8n hasn't verified Git Bash end-to-end. The agentic tools are friendlier to native Windows: Grok Bot ships x64/Arm64 Windows installers, and Hermes ships install.ps1.
Is self-hosted n8n free for business use?
Internal business use is free under n8n's Sustainable Use License (fair-code, 2022) — with three limitations. Commercial redistribution requires a commercial agreement, and the .ee files live under the Enterprise License instead.
Can I install n8n on Ubuntu or a VPS?
Yes — the same two methods work on any Linux server, with the same minimum of 4 GB RAM and 2 vCPUs, and the docs' production guidance (Postgres, hardened examples) carries over unchanged. If the Linux server itself is the new part, we keep notes from our community Linux workshop.
After install: first workflow and agents (Preview)
Build something small first — one working workflow under your fingers before anything agentic matters. Worth knowing as of this writing: self-hosted n8n carries a first-class agents module in Preview, available from n8n 2.32.3 — "an autonomous assistant you build in n8n," with a model, instructions, tools (including MCP servers), skills, channels like Slack and Telegram, schedules, and sub-agents. It isn't yet available on self-hosted Enterprise, so read that as an area still moving.
That's the install half. The wiring — models, MCP, Hermes, Grok Bot — is documented above. And if you'd rather have someone else run and maintain the whole stack, that's what our development practice does: AI-agent automation and self-hosted n8n setups for clients.
Sources
First-party sources (id — publisher — URL — date), per the source-pack rows on card t_0ff1f1af. Date method: B = last commit date of the page's source file in the vendor's docs repo; A = date printed on the page; C = date not stated, retrieved 2026-10-15. Human-facing URLs are shown; the pack's raw-fetch .md paths resolve to the same pages.
- n8n-host — n8n — https://docs.n8n.io/deploy/host-n8n/ — C (retrieved 2026-10-15)
- n8n-choose — n8n — https://docs.n8n.io/choose-how-to-use-n8n/ — C (retrieved 2026-10-15)
- n8n-1line — n8n — https://docs.n8n.io/deploy/host-n8n/install-options/one-line-setup/ — B 2026-10-12
- n8n-docker — n8n — https://docs.n8n.io/deploy/host-n8n/install-options/install-with-docker/ — B 2026-10-12
- n8n-compose — n8n — https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose/ — B 2026-10-12
- n8n-npm — n8n — https://docs.n8n.io/deploy/host-n8n/install-options/install-with-npm/ — B 2026-10-12
- n8n-hosting-repo — n8n — https://github.com/n8n-io/n8n-hosting — C (retrieved 2026-10-15)
- n8n-agent — n8n — https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/ — B 2024-09-23 (page long-stable; noted in text)
- n8n-xai-node — n8n — https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.lmchatxaigrok/ — B 2026-10-12
- n8n-xai-creds — n8n — https://docs.n8n.io/integrations/builtin/credentials/xai/ — B 2026-10-12
- n8n-anthropic — n8n — https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.lmchatanthropic/ — B 2026-10-12
- n8n-mcp — n8n — https://docs.n8n.io/connect/connect-to-n8n-mcp-server/ — B 2026-10-12
- n8n-mcp-examples — n8n — https://docs.n8n.io/connect/connect-to-n8n-mcp-server/mcp-client-examples/ — B 2026-10-12
- n8n-license — n8n — https://docs.n8n.io/n8n-community-license/community-license/ — C (retrieved 2026-10-15)
- n8n-ai-assistant — n8n — https://docs.n8n.io/deploy/host-n8n/configure-n8n/set-up-ai-assistant/ — B 2026-09-08
- n8n-starter-kit — n8n — https://docs.n8n.io/deploy/host-n8n/deploy-with-the-ai-starter-kit/ (repo: https://github.com/n8n-io/self-hosted-ai-starter-kit) — B 2026-10-12
- n8n-agents — n8n — https://docs.n8n.io/build/build-and-manage-agents/ — B 2026-10-12
- xai-grokbot — xAI (docs branded "SpaceX Super Intelligence"/SpaceXSI) — https://docs.x.ai/grok-bot — A: last updated October 7, 2026
- xai-grokbot-start — xAI (SpaceXSI) — https://docs.x.ai/grok-bot/get-started — A: last updated October 12, 2026; downloads at https://x.ai/bot
- xai-api — xAI (SpaceXSI) — https://docs.x.ai/overview — C (retrieved 2026-10-15)
- xai-models — xAI (SpaceXSI) — https://docs.x.ai/developers/models — A: last updated September 21, 2026
- xai-relnotes — xAI (SpaceXSI) — https://docs.x.ai/developers/release-notes — rolling changelog; cited entry: "Grok Bot is now available," August 2026
- xai-tools — xAI (SpaceXSI) — https://docs.x.ai/developers/tools/function-calling — C (retrieved 2026-10-15)
- anthropic-agents — Anthropic — https://www.anthropic.com/engineering/building-effective-agents — A: published December 19, 2024 (page carries an update note re: current approach; staleness caveat stated in text)
- anthropic-mcp — Anthropic — https://www.anthropic.com/news/model-context-protocol — A: November 25, 2024
- anthropic-mcp-connector — Anthropic — https://docs.claude.com/en/docs/agents-and-tools/mcp-connector — C (retrieved 2026-10-15)
- hermes-index — Nous Research — https://hermes-agent.nousresearch.com/docs — C (retrieved 2026-10-15)
- hermes-install — Nous Research — https://hermes-agent.nousresearch.com/docs/getting-started/installation — B 2026-10-07
- hermes-quickstart — Nous Research — https://hermes-agent.nousresearch.com/docs/getting-started/quickstart — B 2026-10-03
- hermes-platform — Nous Research — https://hermes-agent.nousresearch.com/docs/getting-started/platform-support — B 2026-10-14
- hermes-botmode — Nous Research — https://hermes-agent.nousresearch.com/docs/user-guide/bot-mode — B 2026-10-06
Internal research (not a public URL): live SERP analysis "how to install n8n," task 10150437-2768-0139-0000-a067cfcad2b3 (2026-10-15) — basis for the 2021-dated forum-result observation; AI-citation pull per t_fca190c2 (tasks 10150438-…-f2c526c12c81 / …-89f75ca0ebe9) — basis for "AI answers already cite the starter-kit pages." Not printed as article claims.