SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Run n8n's Nod AI agent on your own VPS

Install Nod, the Apache-2.0 agent from the n8n team, on a VPS with Docker Compose. Keep port 4310 private and back up the Vault key before real use.

What Nod is, and what you are building

Nod is a personal AI agent from the team behind n8n. You can run it on a VPS with the Docker Compose kit in its own repository. This guide pins the kit to tag nod-v0.8.1 and keeps the app on a private port. You reach it through an SSH tunnel or over HTTPS. The backup step is part of the install, because saved credentials cannot be recovered without one key.

The README describes Nod as an agent with its own computer and browser: "It chases invoices, preps your calls and cancels trials, on real websites. It runs on your machine with the model you choose, and asks before it acts for you." You talk to it in one chat. It has its own Linux workspace and a browser, and it connects to Gmail, Calendar, Slack, Notion and the web.

Two facts set expectations before you install anything. First, the README labels Nod a "research preview". The docs site also carries an "Early preview" banner that says "Expect rough edges and breaking changes." Second, the README says Nod's safety check "is a model's judgement". Treat it as a preview tool. Give it access only to accounts you are willing to test with.

A VPS suits Nod for one plain reason. The docs say schedules run only while the machine running Nod is on. A laptop sleeps. A server does not.

How Nod differs from an n8n AI Agent workflow

Nod is not the n8n AI Assistant, and you do not need n8n to run it. The README answers the question "Do I need n8n?" with: "No. Nod is its own app, made by the team behind n8n. It is not the n8n AI Assistant."

The n8n docs describe the AI Agent node like this: "Connect a chat model and one or more tools, and the agent decides which tools to call to complete a task." You build that agent inside the n8n editor, and you must connect at least one tool sub-node to it. If that is the job you have, building an AI Agent node workflow in n8n covers it. Self-hosting n8n on a VPS with Docker and HTTPS gives you the n8n server to build it on.

Here is our reading of the two sets of docs. An AI Agent node is one agent that you design, node by node, inside n8n. Nod is a finished chat app with its own workspace and browser, and you give it tasks in plain language. No vendor page compares the two, so take that as a summary, not an official position.

The two can work together. Nod's n8n page says "Connect your n8n once, then ask for it by name in chat." Nod can then build "an n8n Agent with the tools and channel you name." If your request does not mention n8n, Nod uses its own tasks and schedules.

The licence: Nod is Apache-2.0, n8n is not

Nod's repository, github.com/n8n-io/nod, is under the Apache License 2.0, and the copyright holder is n8n GmbH. The README footer reads "Copyright 2026 n8n GmbH · Apache License 2.0". Bundled third-party assets, such as the Geist font, provider logos and desktop runtime components, keep their own terms.

n8n itself uses a different licence. Its code outside files marked .ee. is under the Sustainable Use License. Its main limit is this sentence: "You may use or modify the software only for your own internal business purposes or for non-commercial or personal use." Apache-2.0 puts no such limit on how you use Nod. If you are deciding what you may build on n8n, read the n8n Sustainable Use License explained before you plan a product around it.

What the VPS needs to run Nod

The self-host docs list Docker Engine 25 or newer with Compose v2, OpenSSL, and sha256sum or shasum. A source build also needs Git. Supported hosts are Linux on AMD64 or ARM64, or a Mac with Docker Desktop.

For size, the docs say: "Start with two CPU cores, 8 GB of memory, and 50 GB of disk." That is a suggested starting point, not a measured minimum. The docs add that simultaneous browser tasks and local models need more capacity. The kit's compose.yaml explains most of the memory figure. It caps the server container at 2 GB, the browser at 3 GB and the workspace at 2 GB. You change those caps with NOD_SERVER_MEMORY, NOD_BROWSER_MEMORY and NOD_WORKSPACE_MEMORY in .env. Postgres and Caddy have no cap.

You do not need a model API key to install. You connect a model in the app after it starts.

Install Docker first if the server does not have it. Docker Compose basics on a VPS walks through it. Then check the versions and add the other tools:

docker version
docker compose version
sudo apt update && sudo apt install -y git openssl

The Server: section of docker version must show version 25 or newer, and docker compose version must succeed. The commands below assume your user can run docker without sudo. If it cannot, add sudo in front of each docker and sh command.

Clone the Nod repository at a pinned tag

The kit lives in deployment/self-host/ and builds its Nod images from your checkout. Nothing Nod-specific is pulled from a registry, so the tag you check out is the version you run.

git clone https://github.com/n8n-io/nod.git
cd nod
git checkout nod-v0.8.1
cd deployment/self-host
ls

ls should list setup.sh, compose.yaml, Caddyfile, backup.sh and restore.sh, among other files. Tags nod-v0.8.0 and nod-v0.8.1 were both cut on 16 November 2026. They are not the newest. As of 21 November 2026, nod-v0.9.1 (20 November) is marked Latest. This guide was checked against the nod-v0.8.1 kit, so it pins that tag. The update section below shows how to move forward.

The third-party images in compose.yaml are pinned by digest, not by :latest: postgres:17-alpine, node:24.21.0-bookworm-slim and caddy:2.11.7-alpine. The Nod images are tagged local by default, through NOD_IMAGE_TAG. Setting that variable does not download a published release.

Generate the secrets with setup.sh

sh setup.sh

setup.sh takes no flags. It copies .env.example to a private .env and fills in four generated values: a Compose project name, NOD_AUTH_TOKEN (from openssl rand -hex 32), NOD_VAULT_KEY (from openssl rand -base64 32) and NOD_POSTGRES_PASSWORD. It then runs chmod 600 .env, so only your user can read the file.

It ends by printing Ready. Run: docker compose --file compose.yaml --env-file .env up -d --build --wait. If .env already exists, it keeps it and prints Using the existing .env. Its keys and data are unchanged. It refuses to run when NOD_AUTH_TOKEN, NOD_VAULT_KEY or NOD_POSTGRES_PASSWORD is already set in your shell. If you exported any of them, unset them first. On an older Docker it stops with Use Docker Engine 25 or newer.

Build and start the stack

docker compose up -d --build --wait
docker compose ps

The first build is slow, because the kit builds the Nod images from source. Keep the terminal open until the command returns. --wait blocks until the services with health checks report healthy, so a return with no error means the stack is up. docker compose ps should show server, postgres, browser and the other services running, with server marked healthy.

If you run docker compose up before setup.sh, Compose refuses to start and prints Run sh setup.sh first. That happens because compose.yaml marks NOD_AUTH_TOKEN as required, and only setup.sh writes it.

To read the server log:

docker compose logs --tail 100 server

The docs say the token is never printed in startup logs.

Port 4310 stays on loopback, and ufw is not what protects it

The server publishes its host port like this in compose.yaml:

'${NOD_BIND_ADDRESS:-127.0.0.1}:${PORT:-4310}:${PORT:-4310}'

So Nod listens on port 4310, and the host side is bound to 127.0.0.1. Only processes on the server itself can connect. Keep it that way.

This matters more than it looks, because Docker-published ports bypass ufw. Docker's documentation says traffic to a published container port "gets diverted before it goes through the ufw firewall settings", "effectively ignoring your firewall configuration." A ufw deny 4310 rule would not protect a port published on all interfaces. The loopback binding is what keeps 4310 private. Why Docker ports bypass ufw shows the mechanism and how to check your own server.

Docker adds one version caveat. In releases older than 28.0.0, hosts on the same layer 2 network segment can reach ports published to localhost. On a VPS that segment is your provider's network, so run Docker 28 or newer if you can.

Do not change NOD_BIND_ADDRESS to 0.0.0.0 to reach the app remotely. The docs say "Never expose PostgreSQL, the browser, the workspace, or the Docker connection." Use one of the two access paths below.

Open Nod through an SSH tunnel

The tunnel needs no domain and no open ports beyond SSH. Run this on your own computer, not on the server:

ssh -L 4310:127.0.0.1:4310 user@203.0.113.10

Keep that session open and visit http://localhost:4310 in your local browser. Leave NOD_PUBLIC_URL at its local default, http://localhost:4310, for this setup. If you changed PORT, change both sides of the tunnel and the browser address to match.

The app asks for the access token. Print it on the server:

grep NOD_AUTH_TOKEN .env

Paste the value after the = into the access form, then finish onboarding and connect a model. The token is required even through the tunnel.

If you reach your servers over Tailscale instead, read Tailscale Serve vs Funnel before you put anything in front of Nod, because Funnel publishes a service to the public internet.

Or serve Nod over HTTPS with the Caddy profile

For a public address, the kit has an https profile. It adds a Caddy container that gets and renews the TLS (transport layer security) certificate and forwards traffic to the server. You need a domain whose DNS record points at the VPS. You also need inbound TCP 80 and 443 open in your provider's network firewall, if it has one.

Edit .env and set the exact origin:

NOD_PUBLIC_URL=https://nod.example.com

NOD_PUBLIC_URL is "the exact origin you open Nod at." Write only the scheme and host. Paths, query strings and fragments are refused. The profile requires an https:// origin on port 443 with a DNS name or IPv4 host. Then start the stack with the profile:

docker compose --profile https up -d --build --wait

Keep adding --profile https to later start, stop and status commands, or Compose leaves the Caddy container out. Open https://nod.example.com and paste the token as above.

Know what this opens. The Caddy service publishes 80:80, 443:443 and 443:443/udp with no bind address, so those ports listen on every interface. They always use host ports 80 and 443, whatever PORT says. Because of the Docker bypass above, ufw will not close them. If you already run a reverse proxy, skip the profile. Point the proxy at 127.0.0.1:4310 and set NOD_PUBLIC_URL to the proxy's HTTPS origin.

Usage data and feedback: check what is on

The docs say "Usage sharing is on for new owners." The data goes to the Nod team's EU-hosted PostHog project, including from independent installs. The deployment must also allow it, and NOD_ANALYTICS_ENABLED=false always disables it.

The kit at nod-v0.8.1 ships NOD_ANALYTICS_ENABLED=false in .env.example, and setup.sh copies that line into your .env. So a fresh install from this guide starts with server-level analytics off. Check it:

grep -n NOD_ANALYTICS_ENABLED .env

If the line is missing or empty, the server treats analytics as allowed whenever it runs in production mode. That can happen with an older or hand-written .env. In that case, set the line to false yourself.

The feedback collector is separate. NOD_FEEDBACK_ENABLED is not in .env.example, and the docs document it as enabled by default. The docs list a full opt-out: set analytics and feedback to false, and leave NOD_ONBOARDING_EMAIL_URL empty.

echo 'NOD_FEEDBACK_ENABLED=false' >> .env
grep -n -e NOD_ANALYTICS_ENABLED -e NOD_FEEDBACK_ENABLED -e NOD_ONBOARDING_EMAIL_URL .env
docker compose up -d --wait server

The last command recreates the server with the new values. Add --profile https if you use it. Owners can also switch sharing in the app under Settings, Privacy & data, Share usage data. Stopping sharing does not delete data already sent.

Back up the Vault key and the data: this step is not optional

NOD_VAULT_KEY is "a base64 32-byte key that encrypts saved credentials". It lives in .env, outside the database. The Vault docs say "Saved credentials can't be read without it." Nod never generates a replacement once encrypted data exists. The self-host page says "the database alone cannot recover saved credentials." Lose the key, and every login you gave Nod is gone, even with a perfect database dump.

So save the key on its own first, in a password manager or another safe place off the server:

grep NOD_VAULT_KEY .env

Then take a full backup with the kit's script. The destination must be an absolute path that does not exist yet:

mkdir -p "$HOME/nod-backups"
chmod 700 "$HOME/nod-backups"
sh backup.sh "$HOME/nod-backups/nod-2026-11-21"

The script stops the server, browser and workspace while it copies, then starts them again. It prints Backup saved: and the path. The directory holds .env, source-commit, a postgres.dump, archives of the server, workspace, tools and browser data, and a complete marker file. Check that the marker is there before you rely on the backup.

The docs say "The backup contains secrets." It holds every generated secret, including the Vault key. Store it encrypted and restrict who can read it. Copy it off the server, because a backup on the same disk is lost with the disk. TLS certificates are not included.

Restore Nod into a fresh checkout

Restore goes into a new folder and a new Compose project. Read the commit the backup was taken from, then check out exactly that commit:

commit="$(cat "$HOME/nod-backups/nod-2026-11-21/source-commit")"
git clone https://github.com/n8n-io/nod.git nod-restored
cd nod-restored
git checkout "$commit"
cd deployment/self-host
sh restore.sh "$HOME/nod-backups/nod-2026-11-21" nod-restored

Do not run setup.sh first. restore.sh needs a checkout with no .env, and a source-commit that matches the checked-out revision. It creates fresh volumes, restores the database, and does not start the app. It ends with Restored into a new project. Review .env before starting Nod.

Stop the original server before you start the restored one. Then run docker compose up -d --build --wait, with --profile https for a public address. Never run docker compose down --volumes on a server you want to keep. It deletes the data volumes.

Update Nod to a newer tag

Back up first. Then, from nod/deployment/self-host:

docker compose stop
git fetch origin --tags
git checkout nod-v0.9.1
docker compose up -d --build --wait

Database migrations run when Nod starts, so you cannot undo an update by checking out the old tag. The docs say "Don't point an older application version at an already upgraded database." Rollback means restoring the pre-update backup into a fresh checkout. Read the release notes before each jump, since the preview label means breaking changes are expected. Do not change COMPOSE_PROJECT_NAME during an update.

To rotate the access token, run openssl rand -hex 32, replace the NOD_AUTH_TOKEN value in .env, and run docker compose up -d --wait server. The old token stops working. Never replace NOD_VAULT_KEY to rotate access.

FAQ

Do I need n8n to run Nod?

No. The README says Nod is its own app, made by the team behind n8n, and it is not the n8n AI Assistant. It runs on its own Docker Compose stack. You can connect an n8n instance later and ask Nod to use it by name, but nothing in the install depends on n8n.

Is Nod open source under the same licence as n8n?

No. Nod is under the Apache License 2.0, copyright n8n GmbH, and bundled third-party assets keep their own terms. n8n's code outside its .ee. files is under the Sustainable Use License, which limits use to internal business, non-commercial or personal purposes. Apache-2.0 has no such use limit.

How do I open Nod on a VPS without a domain?

Use an SSH tunnel from your own computer: ssh -L 4310:127.0.0.1:4310 user@203.0.113.10. Keep it open, visit http://localhost:4310, and paste NOD_AUTH_TOKEN from the server's .env. Leave NOD_PUBLIC_URL at its local default. Port 4310 stays bound to loopback on the server, so nothing new is exposed.

What happens if I lose NOD_VAULT_KEY?

Saved credentials cannot be read again. The key encrypts them and is stored in .env, outside the database. Nod will not generate a replacement once encrypted data exists, so a database dump alone does not help. Keep a copy of the key off the server. Run sh backup.sh with an absolute path too, because the backup carries .env with the key.

Does ufw protect Nod's ports?

Not the ports Docker publishes. Docker sends traffic to published container ports around ufw's rules. Port 4310 is private only because compose.yaml binds it to 127.0.0.1. The https profile publishes 80, 443 and 443/udp on every interface, so ufw cannot close them. On Docker older than 28.0.0, hosts on the same layer 2 segment can also reach ports published to localhost.

Was this article useful?