Como instalar o agente Nod do n8n no seu VPS
Instale o Nod, agente Apache-2.0 da equipa do n8n, com Docker Compose. Mantenha a porta 4310 privada e faça backup da chave Vault antes de usar.
O que é o Nod e o que está a construir
O Nod é um agente de IA pessoal da equipa responsável pelo n8n. Pode executá-lo num VPS com o kit Docker Compose do seu próprio repositório. Este guia fixa o kit na tag nod-v0.8.1 e mantém a aplicação numa porta privada. Pode aceder-lhe através de um túnel SSH ou por HTTPS. O backup faz parte da instalação, porque as credenciais guardadas não podem ser recuperadas sem uma chave.
O README descreve o Nod como um agente com o seu próprio computador e browser: "Persegue faturas, prepara as suas chamadas e cancela períodos de teste em sites reais. É executado na sua máquina com o modelo que escolher e pergunta antes de agir em seu nome." Fala com ele numa única conversa. Tem o seu próprio espaço de trabalho Linux e um browser, e liga-se ao Gmail, Calendar, Slack, Notion e à web.
Dois factos definem as expectativas antes de instalar qualquer coisa. Primeiro, o README identifica o Nod como uma "pré-visualização de investigação". O site da documentação também apresenta um banner "Pré-visualização inicial" que diz "Conte com limitações e alterações incompatíveis." Segundo, o README diz que a verificação de segurança do Nod "é o julgamento de um modelo". Trate-o como uma ferramenta de pré-visualização. Dê-lhe acesso apenas a contas que esteja disposto a usar em testes.
Um VPS é adequado para o Nod por uma razão simples. A documentação diz que as tarefas agendadas só são executadas enquanto a máquina que executa o Nod estiver ligada. Um portátil entra em suspensão. Um servidor não.
Como o Nod difere de um workflow de agente de IA do n8n
O Nod não é o n8n AI Assistant, e não precisa do n8n para funcionar. O README responde à pergunta "Preciso do n8n?" com: "Não. O Nod é uma aplicação própria, criada pela equipa responsável pelo n8n. Não é o n8n AI Assistant."
A documentação do n8n descreve o nó AI Agent da seguinte forma: "Ligue um modelo de chat e uma ou mais ferramentas, e o agente decide que ferramentas deve chamar para concluir uma tarefa." Esse agente é criado dentro do editor do n8n, e é necessário ligar pelo menos um subnó de ferramenta a ele. Se esse for o trabalho que precisa de fazer, criar um workflow com um nó AI Agent no n8n explica como proceder. Alojar o n8n num VPS com Docker e HTTPS fornece o servidor n8n onde pode criar esse workflow.
Esta é a nossa leitura dos dois conjuntos de documentação. Um nó AI Agent é um agente que configura nó a nó dentro do n8n. O Nod é uma aplicação de chat pronta, com o seu próprio workspace e browser, à qual atribui tarefas em linguagem natural. Nenhuma página do fornecedor compara os dois, por isso considere isto um resumo, não uma posição oficial.
Os dois podem funcionar em conjunto. A página do Nod sobre o n8n diz: "Ligue o seu n8n uma vez e depois peça-o pelo nome no chat." O Nod pode então criar "um agente n8n com as ferramentas e o canal que indicar". Se o pedido não mencionar o n8n, o Nod usa as suas próprias tarefas e agendas.
A licença: Nod é Apache-2.0, n8n não
O repositório do Nod, github.com/n8n-io/nod, está sob a Apache License 2.0, e o titular dos direitos de autor é a n8n GmbH. O rodapé do README diz "Copyright 2026 n8n GmbH · Apache License 2.0". Os recursos de terceiros incluídos, como o tipo de letra Geist, os logótipos dos fornecedores e os componentes do runtime para desktop, mantêm os seus próprios termos.
O próprio n8n usa uma licença diferente. O código que não está nos ficheiros marcados com .ee. está sob a Sustainable Use License. A principal limitação está nesta frase: "You may use or modify the software only for your own internal business purposes or for non-commercial or personal use." A Apache-2.0 não impõe essa limitação à utilização do Nod. Se está a decidir o que pode criar com base no n8n, leia a explicação da Sustainable Use License do n8n antes de planear um produto baseado nele.
O que o VPS precisa para executar o Nod
A documentação de instalação própria lista o Docker Engine 25 ou mais recente com Compose v2, OpenSSL e sha256sum ou shasum. Uma compilação a partir do código-fonte também precisa do Git. Os hosts compatíveis são Linux em AMD64 ou ARM64, ou um Mac com Docker Desktop.
Quanto ao dimensionamento, a documentação indica: "Comece com dois núcleos de CPU, 8 GB de memória e 50 GB de disco." Esse valor é uma recomendação inicial, não um mínimo medido. A documentação acrescenta que tarefas simultâneas no browser e modelos locais precisam de mais capacidade. O compose.yaml do kit explica a maior parte do valor de memória. Ele limita o contentor do servidor a 2 GB, o browser a 3 GB e o workspace a 2 GB. Pode alterar esses limites com NOD_SERVER_MEMORY, NOD_BROWSER_MEMORY e NOD_WORKSPACE_MEMORY em .env. O Postgres e o Caddy não têm limite.
Não precisa de uma chave de API de modelo para instalar. Ligue um modelo na aplicação depois de ela iniciar.
Instale primeiro o Docker se o servidor não o tiver. Noções básicas do Docker Compose num VPS explica o procedimento. Depois, confirme as versões e adicione as outras ferramentas:
docker version
docker compose version
sudo apt update && sudo apt install -y git opensslA secção Server: de docker version deve mostrar a versão 25 ou mais recente, e docker compose version deve ser executado com sucesso. Os comandos abaixo pressupõem que o seu utilizador pode executar docker sem sudo. Se não puder, adicione sudo antes de cada comando docker e sh.
Clonar o repositório Nod numa tag fixa
O kit fica em deployment/self-host/ e cria as imagens Nod a partir da sua cópia de trabalho. Nenhum componente específico do Nod é obtido de um registry, portanto a tag que selecionar será a versão executada.
git clone https://github.com/n8n-io/nod.git
cd nod
git checkout nod-v0.8.1
cd deployment/self-host
lsls deve listar setup.sh, compose.yaml, Caddyfile, backup.sh e restore.sh, entre outros ficheiros. As tags nod-v0.8.0 e nod-v0.8.1 foram criadas em 16 November 2026. Não são as mais recentes. Em 21 November 2026, nod-v0.9.1 (20 November) está marcada como Latest. Este guia foi verificado com o kit nod-v0.8.1, por isso fixa essa tag. A secção abaixo mostra como avançar para uma versão mais recente.
As imagens de terceiros em compose.yaml são fixadas por digest, não por :latest: postgres:17-alpine, node:24.21.0-bookworm-slim e caddy:2.11.7-alpine. Por predefinição, as imagens Nod usam a tag local, através de NOD_IMAGE_TAG. Definir essa variável não descarrega uma versão publicada.
Gere os segredos com setup.sh
sh setup.shsetup.sh não aceita opções. Copia .env.example para um .env privado e preenche quatro valores gerados: um nome de projeto do Compose, NOD_AUTH_TOKEN (a partir de openssl rand -hex 32), NOD_VAULT_KEY (a partir de openssl rand -base64 32) e NOD_POSTGRES_PASSWORD. Em seguida, executa chmod 600 .env, para que apenas o seu utilizador possa ler o ficheiro.
No final, imprime Ready. Run: docker compose --file compose.yaml --env-file .env up -d --build --wait. Se .env já existir, mantém-no e imprime Using the existing .env. Its keys and data are unchanged.. Recusa-se a executar quando NOD_AUTH_TOKEN, NOD_VAULT_KEY ou NOD_POSTGRES_PASSWORD já estiver definido na sua shell. Se tiver exportado algum deles, faça unset primeiro. Numa versão mais antiga do Docker, termina com Use Docker Engine 25 or newer.
Compile e inicie a stack
docker compose up -d --build --wait
docker compose psA primeira compilação é lenta, porque o kit compila as imagens Nod a partir do código-fonte. Mantenha o terminal aberto até o comando terminar. --wait bloqueia até que os serviços com verificações de integridade reportem um estado saudável. Portanto, se o comando terminar sem erro, a stack está em execução. docker compose ps deve mostrar server, postgres, browser e os outros serviços em execução, com server marcado como saudável.
Se executar docker compose up antes de setup.sh, o Compose recusa-se a iniciar e apresenta Run sh setup.sh first. Isso acontece porque compose.yaml marca NOD_AUTH_TOKEN como obrigatório, e apenas setup.sh o escreve.
Para consultar o log do servidor:
docker compose logs --tail 100 serverA documentação informa que o token nunca é apresentado nos logs de arranque.
A porta 4310 permanece no loopback, e o ufw não é o que a protege
O servidor publica a porta do host desta forma em compose.yaml:
'${NOD_BIND_ADDRESS:-127.0.0.1}:${PORT:-4310}:${PORT:-4310}'Assim, o Nod escuta na porta 4310, e o lado do host está associado a 127.0.0.1. Apenas processos no próprio servidor podem ligar-se a ela. Mantenha essa configuração.
Isto é mais importante do que parece, porque as portas publicadas pelo Docker contornam o ufw. A documentação do Docker diz que o tráfego para uma porta de contentor publicada é "desviado antes de passar pelas definições da firewall ufw", "ignorando efetivamente a configuração da firewall". Uma regra ufw deny 4310 não protegeria uma porta publicada em todas as interfaces. É a associação ao loopback que mantém a porta 4310 privada. Por que as portas do Docker contornam o ufw explica o mecanismo e mostra como verificar o seu próprio servidor.
O Docker acrescenta uma ressalva relacionada com a versão. Nas releases anteriores à 28.0.0, os hosts no mesmo segmento de rede de camada 2 podem aceder às portas publicadas no localhost. Num VPS, esse segmento é a rede do seu fornecedor. Por isso, use o Docker 28 ou posterior, se possível.
Não altere NOD_BIND_ADDRESS para 0.0.0.0 para aceder remotamente à aplicação. A documentação diz: "Nunca exponha o PostgreSQL, o browser, o workspace ou a ligação do Docker." Use um dos dois métodos de acesso abaixo.
Abrir o Nod através de um túnel SSH
O túnel não requer um domínio nem portas abertas além da porta SSH. Execute isto no seu próprio computador, não no servidor:
ssh -L 4310:127.0.0.1:4310 user@203.0.113.10Mantenha essa sessão aberta e aceda a http://localhost:4310 no navegador local. Para esta configuração, deixe NOD_PUBLIC_URL no valor predefinido local, http://localhost:4310. Se alterou PORT, altere os dois lados do túnel e o endereço do navegador para corresponder.
A aplicação pede o token de acesso. Apresente-o no servidor:
grep NOD_AUTH_TOKEN .envCole o valor depois de = no formulário de acesso. Em seguida, conclua a configuração inicial e ligue um modelo. O token é obrigatório mesmo através do túnel.
Se aceder aos seus servidores através do Tailscale, leia Tailscale Serve vs Funnel antes de colocar qualquer coisa à frente do Nod, porque o Funnel publica um serviço na internet pública.
Ou sirva o Nod por HTTPS com o perfil Caddy
Para um endereço público, o kit tem um perfil https. Esse perfil adiciona um contentor Caddy que obtém e renova o certificado TLS (transport layer security) e encaminha o tráfego para o servidor. Precisa de um domínio cujo registo DNS aponte para o VPS. Também precisa de permitir a entrada de TCP 80 e 443 na firewall de rede do seu fornecedor, se existir.
Edite .env e defina a origem exata:
NOD_PUBLIC_URL=https://nod.example.comNOD_PUBLIC_URL é "a origem exata onde abre o Nod". Escreva apenas o esquema e o host. Caminhos, cadeias de consulta e fragmentos são recusados. O perfil exige uma origem https:// na porta 443, com um nome DNS ou um host IPv4. Em seguida, inicie a stack com o perfil:
docker compose --profile https up -d --build --waitContinue a adicionar --profile https aos comandos posteriores de arranque, paragem e estado, caso contrário o Compose exclui o contentor Caddy. Abra https://nod.example.com e cole o token como indicado acima.
Saiba o que isto expõe. O serviço Caddy publica 80:80, 443:443 e 443:443/udp sem um endereço de bind, pelo que essas portas escutam em todas as interfaces. Usam sempre as portas 80 e 443 do host, independentemente do que PORT indicar. Devido ao bypass do Docker referido acima, o ufw não as fecha. Se já executar um reverse proxy, ignore o perfil. Aponte o proxy para 127.0.0.1:4310 e defina NOD_PUBLIC_URL como a origem HTTPS do proxy.
Dados de utilização e feedback: verifique o que está ativado
A documentação indica que "a partilha de utilização está ativada para novos proprietários". Os dados são enviados para o projeto PostHog da equipa Nod, alojado na UE, incluindo dados de instalações independentes. A implementação também tem de permitir essa partilha, e NOD_ANALYTICS_ENABLED=false desativa-a sempre.
O kit em nod-v0.8.1 inclui NOD_ANALYTICS_ENABLED=false em .env.example, e setup.sh copia essa linha para o seu .env. Por isso, uma instalação nova deste guia começa com a análise ao nível do servidor desativada. Verifique:
grep -n NOD_ANALYTICS_ENABLED .envSe a linha estiver ausente ou vazia, o servidor considera que a análise está permitida quando é executado em modo de produção. Isto pode acontecer com um .env antigo ou criado manualmente. Nesse caso, defina a linha como false.
O coletor de feedback é separado. NOD_FEEDBACK_ENABLED não está em .env.example, e a documentação indica que está ativado por predefinição. A documentação descreve uma desativação completa: defina a análise e o feedback como false e deixe NOD_ONBOARDING_EMAIL_URL vazio.
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 serverO último comando recria o servidor com os novos valores. Adicione --profile https se o utilizar. Os proprietários também podem alterar a partilha na aplicação, em Settings, Privacy & data, Share usage data. Parar a partilha não elimina os dados já enviados.
Faça backup da chave do Vault e dos dados: esta etapa é obrigatória
NOD_VAULT_KEY é "uma chave de 32 bytes em base64 que cifra as credenciais guardadas". Ela fica em .env, fora da base de dados. A documentação do Vault diz: "Não é possível ler as credenciais guardadas sem ela." O Nod nunca gera uma substituta depois de existirem dados cifrados. A página de alojamento próprio diz: "A base de dados, por si só, não consegue recuperar as credenciais guardadas." Se perder a chave, perde todos os logins fornecidos ao Nod, mesmo com um dump perfeito da base de dados.
Por isso, guarde primeiro a chave separadamente, num gestor de palavras-passe ou noutro local seguro fora do servidor:
grep NOD_VAULT_KEY .envDepois, faça um backup completo com o script do kit. O destino tem de ser um caminho absoluto que ainda não exista:
mkdir -p "$HOME/nod-backups"
chmod 700 "$HOME/nod-backups"
sh backup.sh "$HOME/nod-backups/nod-2026-11-21"O script para o servidor, o browser e o workspace enquanto copia os dados e inicia-os novamente depois. Apresenta Backup saved: e o caminho. O diretório contém .env, source-commit, um postgres.dump, arquivos do servidor, workspace, ferramentas e dados do browser, além de um ficheiro marcador complete. Confirme que o marcador está presente antes de confiar no backup.
A documentação diz: "O backup contém segredos." Ele inclui todos os segredos gerados, incluindo a chave do Vault. Guarde-o cifrado e restrinja quem pode lê-lo. Copie-o para fora do servidor, porque um backup no mesmo disco perde-se com o disco. Os certificados TLS não estão incluídos.
Restaure o Nod numa checkout nova
A restauração é feita numa pasta nova e num projeto Compose novo. Leia o commit a partir do qual a cópia de segurança foi criada e, em seguida, faça checkout exatamente desse 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-restoredNão execute setup.sh primeiro. restore.sh precisa de uma checkout sem .env e de um source-commit que corresponda à revisão selecionada. Cria volumes novos, restaura a base de dados e não inicia a aplicação. Termina com Restored into a new project. Review .env before starting Nod.
Pare o servidor original antes de iniciar o servidor restaurado. Em seguida, execute docker compose up -d --build --wait, usando --profile https para um endereço público. Nunca execute docker compose down --volumes num servidor que pretende manter. O comando elimina os volumes de dados.
Atualizar o Nod para uma tag mais recente
Faça primeiro uma cópia de segurança. Em seguida, a partir de nod/deployment/self-host:
docker compose stop
git fetch origin --tags
git checkout nod-v0.9.1
docker compose up -d --build --waitAs migrações da base de dados são executadas quando o Nod arranca. Por isso, não é possível desfazer uma atualização fazendo checkout da tag antiga. A documentação diz: "Não aponte uma versão mais antiga da aplicação para uma base de dados já atualizada." Para fazer rollback, restaure a cópia de segurança anterior à atualização num checkout novo. Leia as notas de versão antes de cada atualização, porque o rótulo preview indica que são esperadas alterações incompatíveis. Não altere COMPOSE_PROJECT_NAME durante uma atualização.
Para fazer a rotação do token de acesso, execute openssl rand -hex 32, substitua o valor NOD_AUTH_TOKEN em .env e execute docker compose up -d --wait server. O token antigo deixa de funcionar. Nunca substitua NOD_VAULT_KEY para fazer a rotação do acesso.
FAQ
Preciso do n8n para executar o Nod?
Não. O README informa que o Nod é uma aplicação independente, criada pela equipa responsável pelo n8n, e não é o n8n AI Assistant. O Nod é executado na sua própria stack do Docker Compose. Pode ligar uma instância do n8n mais tarde e pedir ao Nod para a utilizar pelo nome, mas a instalação não depende do n8n.
O Nod é open source com a mesma licença do n8n?
Não. O Nod está sujeito à Apache License 2.0, com copyright da n8n GmbH, e os ativos de terceiros incluídos mantêm os seus próprios termos. O código do n8n fora dos ficheiros .ee. está sujeito à Sustainable Use License, que limita a utilização a fins empresariais internos, não comerciais ou pessoais. A Apache-2.0 não impõe essa limitação de utilização.
Como abro o Nod num VPS sem um domínio?
Use um túnel SSH a partir do seu próprio computador: ssh -L 4310:127.0.0.1:4310 user@203.0.113.10. Mantenha-o aberto, aceda a http://localhost:4310 e cole NOD_AUTH_TOKEN do .env do servidor. Mantenha NOD_PUBLIC_URL no valor predefinido local. A porta 4310 continua associada ao loopback no servidor, por isso nada de novo fica exposto.
O que acontece se eu perder NOD_VAULT_KEY?
As credenciais guardadas deixam de poder ser lidas. A chave cifra essas credenciais e é armazenada em .env, fora da base de dados. O Nod não gera uma chave substituta depois de existirem dados cifrados, por isso apenas um dump da base de dados não resolve o problema. Mantenha uma cópia da chave fora do servidor. Execute também sh backup.sh com um caminho absoluto, porque a cópia de segurança inclui .env com a chave.
O ufw protege as portas do Nod?
Não protege as portas publicadas pelo Docker. O Docker encaminha o tráfego para as portas publicadas dos contentores, contornando as regras do ufw. A porta 4310 é privada apenas porque compose.yaml a associa a 127.0.0.1. O perfil https publica 80, 443 e 443/udp em todas as interfaces, por isso o ufw não as consegue fechar. Em versões do Docker anteriores a 28.0.0, os hosts no mesmo segmento de camada 2 também podem alcançar portas publicadas no localhost.