Come eseguire l'agente Nod di n8n su un VPS
Installa Nod, l'agente Apache-2.0 del team n8n, con Docker Compose su un VPS. Tieni privata la porta 4310 e salva la chiave Vault prima dell'uso.
Che cos'è Nod e che cosa stai configurando
Nod è un agente AI personale del team che sviluppa n8n. Puoi eseguirlo su un VPS con il kit Docker Compose disponibile nel relativo repository. Questa guida fissa il kit al tag nod-v0.8.1 e mantiene l'applicazione su una porta privata. Puoi raggiungerla tramite un tunnel SSH o tramite HTTPS. Il backup fa parte dell'installazione, perché le credenziali salvate non possono essere recuperate senza una chiave.
Il README descrive Nod come un agente con un computer e un browser propri: "Gestisce fatture, prepara le tue chiamate e annulla i periodi di prova su siti web reali. Viene eseguito sulla tua macchina con il modello che scegli e chiede conferma prima di agire per te." Interagisci con Nod tramite un'unica chat. Dispone di un workspace Linux e di un browser propri e si connette a Gmail, Calendar, Slack, Notion e al Web.
Prima di installare qualsiasi componente, considera due aspetti. Innanzitutto, il README definisce Nod una "anteprima di ricerca". Anche il sito della documentazione mostra il banner "Anteprima iniziale", con il messaggio "Sono possibili problemi e modifiche incompatibili." Inoltre, il README afferma che il controllo di sicurezza di Nod "è il giudizio di un modello". Consideralo uno strumento in anteprima. Concedigli l'accesso soltanto agli account che sei disposto a usare per i test.
Un VPS è adatto a Nod per un motivo semplice. La documentazione specifica che le attività pianificate vengono eseguite soltanto mentre la macchina che esegue Nod è accesa. Un laptop entra in sospensione. Un server no.
Differenze tra Nod e un workflow n8n con AI Agent
Nod non è n8n AI Assistant e non richiede n8n per funzionare. Il README risponde così alla domanda «È necessario n8n?»: «No. Nod è un'applicazione autonoma, sviluppata dal team che ha creato n8n. Non è n8n AI Assistant.»
La documentazione di n8n descrive il nodo AI Agent in questo modo: «Collega un modello chat e uno o più strumenti; l'agente decide quali strumenti chiamare per completare un'attività.» L'agente viene creato nell'editor di n8n e deve avere collegato almeno un sottonodo strumento. Se questo è il risultato che vuoi ottenere, creare un workflow con un nodo AI Agent in n8n illustra la procedura. Self-hosting di n8n su un VPS con Docker e HTTPS fornisce il server n8n su cui crearlo.
Questa è la nostra interpretazione dei due insiemi di documentazione. Un nodo AI Agent è un singolo agente che progetti nodo per nodo all'interno di n8n. Nod è un'applicazione chat completa, con un proprio workspace e un browser, a cui assegni attività usando il linguaggio naturale. Nessuna pagina ufficiale confronta i due prodotti, quindi considera questa descrizione una sintesi e non una posizione ufficiale.
I due strumenti possono funzionare insieme. La pagina di Nod dedicata a n8n dice: «Collega n8n una sola volta, quindi richiamalo per nome nella chat.» Nod può quindi creare «un Agent n8n con gli strumenti e il canale che specifichi». Se la richiesta non menziona n8n, Nod usa le proprie attività e pianificazioni.
La licenza: Nod è rilasciato con Apache-2.0, n8n no
Il repository di Nod, github.com/n8n-io/nod, è distribuito con la Apache License 2.0 e il detentore del copyright è n8n GmbH. Il piè di pagina del README riporta "Copyright 2026 n8n GmbH · Apache License 2.0". Gli asset di terze parti inclusi, come il font Geist, i loghi dei provider e i componenti del runtime desktop, mantengono i propri termini di licenza.
n8n utilizza una licenza diversa. Il relativo codice, ad eccezione dei file contrassegnati con .ee., è soggetto alla Sustainable Use License. Il limite principale è espresso nella seguente frase: "È possibile utilizzare o modificare il software esclusivamente per finalità aziendali interne proprie oppure per usi non commerciali o personali." La licenza Apache-2.0 non impone limiti analoghi all'utilizzo di Nod. Se devi decidere cosa puoi realizzare con n8n, leggi la spiegazione della Sustainable Use License di n8n prima di progettare un prodotto basato su di esso.
Requisiti del VPS per eseguire Nod
La documentazione per l'installazione self-hosted richiede Docker Engine 25 o versione successiva con Compose v2, OpenSSL e sha256sum o shasum. Una compilazione dai sorgenti richiede anche Git. Gli host supportati sono sistemi Linux su AMD64 o ARM64 oppure un Mac con Docker Desktop.
Per le dimensioni, la documentazione indica: "Inizia con 2 core CPU, 8 GB di memoria e 50 GB di spazio su disco." Si tratta di una configurazione iniziale consigliata, non di un minimo misurato. La documentazione specifica inoltre che le attività simultanee del browser e i modelli locali richiedono maggiore capacità. Il file compose.yaml del kit spiega la maggior parte del requisito di memoria. Imposta un limite di 2 GB per il container del server, 3 GB per il browser e 2 GB per il workspace. Puoi modificare questi limiti con NOD_SERVER_MEMORY, NOD_BROWSER_MEMORY e NOD_WORKSPACE_MEMORY in .env. Postgres e Caddy non hanno limiti configurati.
Non è necessaria una chiave API del modello per l'installazione. Puoi collegare un modello nell'applicazione dopo l'avvio.
Installa prima Docker se il server non lo include. La guida Nozioni di base su Docker Compose su un VPS illustra la procedura. Controlla quindi le versioni e installa gli altri strumenti:
docker version
docker compose version
sudo apt update && sudo apt install -y git opensslLa sezione Server: di docker version deve mostrare la versione 25 o successiva e docker compose version deve essere eseguito correttamente. I comandi seguenti presuppongono che il tuo utente possa eseguire docker senza sudo. In caso contrario, aggiungi sudo prima di ogni comando docker e sh.
Clonare il repository Nod a un tag fissato
Il kit si trova in deployment/self-host/ e crea le immagini Nod a partire dal checkout locale. Dal registry non viene scarunicato alcun contenuto specifico di Nod, quindi il tag estratto determina la versione eseguita.
git clone https://github.com/n8n-io/nod.git
cd nod
git checkout nod-v0.8.1
cd deployment/self-host
lsls dovrebbe contenere, tra gli altri file, setup.sh, compose.yaml, Caddyfile, backup.sh e restore.sh. I tag nod-v0.8.0 e nod-v0.8.1 sono stati creati entrambi il 16 novembre 2026. Non sono i più recenti. Al 21 novembre 2026, nod-v0.9.1 (20 novembre) è contrassegnato come Latest. Questa guida è stata verificata con il kit nod-v0.8.1, quindi fissa quel tag. La sezione seguente mostra come procedere con l'aggiornamento.
Le immagini di terze parti in compose.yaml sono fissate tramite digest, non tramite :latest: postgres:17-alpine, node:24.21.0-bookworm-slim e caddy:2.11.7-alpine. Per impostazione predefinita, le immagini Nod usano il tag local, tramite NOD_IMAGE_TAG. L'impostazione di questa variabile non scarica una release pubblicata.
Generare i secret con setup.sh
sh setup.shsetup.sh non accetta flag. Copia .env.example in un file privato .env e inserisce quattro valori generati: il nome del progetto Compose, NOD_AUTH_TOKEN (da openssl rand -hex 32), NOD_VAULT_KEY (da openssl rand -base64 32) e NOD_POSTGRES_PASSWORD. Esegue quindi chmod 600 .env, in modo che solo il proprio utente possa leggere il file.
Al termine stampa Ready. Run: docker compose --file compose.yaml --env-file .env up -d --build --wait. Se .env esiste già, lo conserva e stampa Using the existing .env. Its keys and data are unchanged. Si rifiuta di essere eseguito se nella shell è già impostato NOD_AUTH_TOKEN, NOD_VAULT_KEY o NOD_POSTGRES_PASSWORD. Se ne hai esportato uno, annullane l'esportazione con unset. Con una versione precedente di Docker si interrompe con Use Docker Engine 25 or newer..
Compilare e avviare lo stack
docker compose up -d --build --wait
docker compose psLa prima compilazione è lenta, perché il kit compila le immagini Nod dal codice sorgente. Lasciare aperto il terminale finché il comando non restituisce il prompt. --wait resta in attesa finché i servizi con i controlli di integrità non risultano integri; quindi, se il comando termina senza errori, lo stack è attivo. docker compose ps dovrebbe mostrare server, postgres, browser e gli altri servizi in esecuzione, con server contrassegnato come integro.
Se si esegue docker compose up prima di setup.sh, Compose rifiuta l'avvio e visualizza Run sh setup.sh first. Questo accade perché compose.yaml indica NOD_AUTH_TOKEN come obbligatorio e solo setup.sh lo scrive.
Per leggere il log del server:
docker compose logs --tail 100 serverLa documentazione specifica che il token non viene mai visualizzato nei log di avvio.
La porta 4310 resta sull'interfaccia loopback e ufw non è il componente che la protegge
Il server pubblica la porta dell'host nel modo seguente in compose.yaml:
'${NOD_BIND_ADDRESS:-127.0.0.1}:${PORT:-4310}:${PORT:-4310}'Nod è quindi in ascolto sulla porta 4310 e il lato host è associato a 127.0.0.1. Solo i processi eseguiti sul server possono connettersi. Mantieni questa configurazione.
Questo aspetto è più importante di quanto sembri, perché le porte pubblicate da Docker bypassano ufw. La documentazione di Docker specifica che il traffico diretto a una porta pubblicata del container «viene deviato prima di passare attraverso le impostazioni del firewall ufw», «ignorando di fatto la configurazione del firewall». Una regola ufw deny 4310 non proteggerebbe una porta pubblicata su tutte le interfacce. È il binding sull'interfaccia loopback a mantenere privata la porta 4310. Perché le porte Docker bypassano ufw spiega il meccanismo e mostra come verificare il comportamento sul proprio server.
Docker introduce un'avvertenza relativa alla versione. Nelle release precedenti alla 28.0.0, gli host presenti sullo stesso segmento di rete layer 2 possono raggiungere le porte pubblicate su localhost. Su un VPS, quel segmento corrisponde alla rete del provider. Se possibile, esegui quindi Docker 28 o una versione successiva.
Non modificare NOD_BIND_ADDRESS in 0.0.0.0 per raggiungere l'applicazione da remoto. La documentazione indica: «Non esporre mai PostgreSQL, il browser, il workspace o la connessione Docker». Usa uno dei due percorsi di accesso riportati di seguito.
Aprire Nod tramite un tunnel SSH
Il tunnel non richiede un dominio né porte aperte aggiuntive oltre a SSH. Eseguire questo comando sul proprio computer, non sul server:
ssh -L 4310:127.0.0.1:4310 user@203.0.113.10Mantenere aperta la sessione e visitare http://localhost:4310 nel browser locale. Per questa configurazione, lasciare NOD_PUBLIC_URL al valore predefinito locale http://localhost:4310. Se è stato modificato PORT, modificare entrambi i lati del tunnel e l'indirizzo del browser in modo coerente.
L'applicazione richiede il token di accesso. Visualizzarlo sul server:
grep NOD_AUTH_TOKEN .envIncollare nel modulo di accesso il valore dopo =, quindi completare la configurazione iniziale e collegare un modello. Il token è richiesto anche tramite il tunnel.
Se invece si accede ai server tramite Tailscale, leggere Tailscale Serve vs Funnel prima di esporre Nod, perché Funnel pubblica un servizio su Internet.
Oppure servi Nod su HTTPS con il profilo Caddy
Per un indirizzo pubblico, il kit include un profilo https. Aggiunge un container Caddy che ottiene e rinnova il certificato TLS (Transport Layer Security) e inoltra il traffico al server. È necessario un dominio il cui record DNS punti al VPS. È inoltre necessario consentire il traffico TCP in ingresso sulle porte 80 e 443 nel firewall di rete del provider, se disponibile.
Modifica .env e imposta l'origine esatta:
NOD_PUBLIC_URL=https://nod.example.comNOD_PUBLIC_URL è «l'origine esatta da cui apri Nod». Scrivi soltanto schema e host. Percorsi, stringhe di query e frammenti vengono rifiutati. Il profilo richiede un'origine https:// sulla porta 443, con un nome DNS o un host IPv4. Avvia quindi lo stack con il profilo:
docker compose --profile https up -d --build --waitContinua ad aggiungere --profile https ai comandi successivi di avvio, arresto e controllo dello stato; in caso contrario Compose esclude il container Caddy. Apri https://nod.example.com e incolla il token come indicato sopra.
Considera quali porte vengono esposte. Il servizio Caddy pubblica 80:80, 443:443 e 443:443/udp senza un indirizzo di bind, quindi queste porte restano in ascolto su tutte le interfacce. Usano sempre le porte host 80 e 443, indipendentemente dal valore di PORT. A causa dell'aggiramento di Docker descritto sopra, ufw non le chiuderà. Se esegui già un reverse proxy, non usare il profilo. Indirizza il proxy a 127.0.0.1:4310 e imposta NOD_PUBLIC_URL sull'origine HTTPS del proxy.
Dati di utilizzo e feedback: verifica cosa è attivo
La documentazione indica che «la condivisione dei dati di utilizzo è attiva per i nuovi owner». I dati vengono inviati al progetto PostHog del team Nod, ospitato nell'UE, anche dalle installazioni indipendenti. Anche la distribuzione deve consentirla e NOD_ANALYTICS_ENABLED=false la disabilita sempre.
Il kit in nod-v0.8.1 include NOD_ANALYTICS_ENABLED=false in .env.example e setup.sh copia quella riga nel tuo .env. Di conseguenza, una nuova installazione eseguita seguendo questa guida parte con l'analytics a livello server disabilitata. Verifica:
grep -n NOD_ANALYTICS_ENABLED .envSe la riga manca o è vuota, il server considera l'analytics consentita ogni volta che viene eseguito in modalità produzione. Questo può accadere con un .env precedente o scritto manualmente. In tal caso, imposta manualmente la riga su false.
Il collector del feedback è separato. NOD_FEEDBACK_ENABLED non si trova in .env.example e la documentazione lo descrive come attivo per impostazione predefinita. La documentazione indica una disattivazione completa: imposta analytics e feedback su false e lascia NOD_ONBOARDING_EMAIL_URL vuoto.
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 serverL'ultimo comando ricrea il server con i nuovi valori. Aggiungi --profile https se lo utilizzi. Gli owner possono anche modificare la condivisione nell'applicazione, in Settings, Privacy & data, Share usage data. L'interruzione della condivisione non elimina i dati già inviati.
Eseguire il backup della chiave Vault e dei dati: questo passaggio è obbligatorio
NOD_VAULT_KEY è “una chiave di 32 byte in base64 che cifra le credenziali salvate”. Si trova in .env, al di fuori del database. La documentazione di Vault specifica che “non è possibile leggere le credenziali salvate senza questa chiave”. Nod non genera mai una chiave sostitutiva quando esistono già dati cifrati. La pagina relativa all’installazione self-hosted specifica che “il solo database non consente di recuperare le credenziali salvate”. Se perdi la chiave, perdi tutti gli accessi che hai fornito a Nod, anche disponendo di un dump completo e integro del database.
Salva quindi prima la chiave separatamente, in un password manager o in un altro luogo sicuro al di fuori del server:
grep NOD_VAULT_KEY .envEsegui quindi un backup completo con lo script del kit. La destinazione deve essere un percorso assoluto che non esista ancora:
mkdir -p "$HOME/nod-backups"
chmod 700 "$HOME/nod-backups"
sh backup.sh "$HOME/nod-backups/nod-2026-11-21"Durante la copia, lo script arresta il server, il browser e l’area di lavoro, quindi li riavvia. Stampa Backup saved: e il percorso. La directory contiene .env, source-commit, un postgres.dump, gli archivi dei dati del server, dell’area di lavoro, degli strumenti e del browser, oltre a un file marcatore complete. Verifica che il marcatore sia presente prima di fare affidamento sul backup.
La documentazione specifica che “il backup contiene secret”. Include tutti i secret generati, compresa la chiave Vault. Conservalo in forma cifrata e limita gli utenti autorizzati a leggerlo. Copialo al di fuori del server, perché un backup sullo stesso disco andrebbe perso insieme al disco. I certificati TLS non sono inclusi.
Ripristinare Nod in un checkout pulito
Il ripristino viene eseguito in una nuova directory e in un nuovo progetto Compose. Leggere il commit da cui è stato creato il backup, quindi eseguire il checkout esattamente di quel 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-restoredNon eseguire prima setup.sh. restore.sh richiede un checkout senza .env e un source-commit corrispondente alla revisione sottoposta a checkout. Crea nuovi volumi, ripristina il database e non avvia l'applicazione. Termina con Restored into a new project. Review .env before starting Nod.
Arrestare il server originale prima di avviare quello ripristinato. Quindi eseguire docker compose up -d --build --wait, specificando --profile https per un indirizzo pubblico. Non eseguire mai docker compose down --volumes su un server che si desidera conservare. Elimina i volumi dati.
Aggiornare Nod a un tag più recente
Prima esegui un backup. Quindi, da nod/deployment/self-host:
docker compose stop
git fetch origin --tags
git checkout nod-v0.9.1
docker compose up -d --build --waitLe migrazioni del database vengono eseguite all'avvio di Nod, quindi non puoi annullare un aggiornamento eseguendo il checkout del vecchio tag. La documentazione indica: "Non indirizzare una versione precedente dell'applicazione verso un database già aggiornato." Per eseguire il rollback, ripristina il backup precedente all'aggiornamento in un checkout separato. Leggi le note di rilascio prima di ogni aggiornamento, perché l'etichetta preview indica che sono previste modifiche incompatibili. Non modificare COMPOSE_PROJECT_NAME durante un aggiornamento.
Per ruotare il token di accesso, esegui openssl rand -hex 32, sostituisci il valore NOD_AUTH_TOKEN in .env e quindi esegui docker compose up -d --wait server. Il vecchio token smette di funzionare. Non sostituire mai NOD_VAULT_KEY per ruotare l'accesso.
FAQ
È necessario n8n per eseguire Nod?
No. Il README indica che Nod è un'applicazione autonoma, sviluppata dal team che gestisce n8n, e non è n8n AI Assistant. Viene eseguito sul proprio stack Docker Compose. In seguito è possibile collegare un'istanza n8n e chiedere a Nod di utilizzarla per nome, ma l'installazione non dipende da n8n.
Nod è open source con la stessa licenza di n8n?
No. Nod è distribuito con Apache License 2.0, il copyright appartiene a n8n GmbH e gli asset di terze parti inclusi mantengono i propri termini. Il codice di n8n al di fuori dei file .ee. è distribuito con Sustainable Use License, che limita l'utilizzo agli scopi aziendali interni, non commerciali o personali. Apache-2.0 non prevede questa limitazione d'uso.
Come posso aprire Nod su un VPS senza un dominio?
Usa un tunnel SSH dal tuo computer: ssh -L 4310:127.0.0.1:4310 user@203.0.113.10. Lascialo aperto, visita http://localhost:4310 e incolla NOD_AUTH_TOKEN dal .env del server. Lascia NOD_PUBLIC_URL al valore predefinito locale. La porta 4310 resta associata all'interfaccia di loopback del server, quindi non viene esposto nulla di nuovo.
Cosa succede se perdo NOD_VAULT_KEY?
Le credenziali salvate non possono più essere lette. La chiave le cifra ed è memorizzata in .env, al di fuori del database. Dopo che sono stati creati dati cifrati, Nod non genera una chiave sostitutiva. Un dump del solo database non è quindi sufficiente. Conserva una copia della chiave al di fuori del server. Esegui anche sh backup.sh con un percorso assoluto, perché il backup contiene .env insieme alla chiave.
ufw protegge le porte di Nod?
Non le porte pubblicate da Docker. Docker inoltra il traffico alle porte dei container pubblicate aggirando le regole di ufw. La porta 4310 è privata soltanto perché compose.yaml la associa a 127.0.0.1. Il profilo https pubblica 80, 443 e 443/udp su tutte le interfacce, quindi ufw non può chiuderle. Con versioni di Docker precedenti alla 28.0.0, anche gli host appartenenti allo stesso segmento di livello 2 possono raggiungere le porte pubblicate su localhost.