Task Runners do n8n 2.0: o que mudou no Code node e o que parou de funcionar
A única camada de isolamento entre o código dos fluxos e suas credenciais: modo interno x externo, a configuração oficial e a pegadinha do modo de fila.
Resumo por IA
Resumo gerado por IA, revisado pela redação.
Task Runners são o mecanismo que executa o código do node Code fora do processo do n8n. A documentação é direta ao dizer que eles são a única camada de isolamento entre o código escrito nos fluxos e o n8n em si — sem eles, quem puder editar um fluxo consegue potencialmente ler seu banco de dados, sua chave de criptografia, suas credenciais armazenadas e suas variáveis de ambiente. Se você roda n8n com dado de cliente, esta aula é a mais importante do módulo.
Adicione ao Google NotíciasO que mudou, e por que
Antes, o código do node Code rodava dentro do próprio processo do n8n. Funcionava — e significava que qualquer pessoa capaz de editar um fluxo tinha, na prática, acesso ao que o n8n acessa.
Numa instância pessoal isso é irrelevante. Numa instância com credenciais de clientes, é uma porta aberta.
Os Task Runners resolvem isso separando a execução do código do resto do sistema. O efeito colateral que gera dúvida: o acesso às variáveis de ambiente do sistema passa a ser bloqueado por padrão dentro do Code. Código que lia configuração dali parou de funcionar — não é defeito, é a proteção agindo.
Como funciona por dentro
São três peças:
Task runner — quem executa o código de fato.
Task broker — coordena a comunicação. É a própria instância do n8n que faz esse papel.
Task requester — quem pede a execução. Nesse caso, o node Code.
Os runners se conectam ao broker por websocket. O requester envia o pedido ao broker, um runner disponível pega a tarefa, executa e devolve o resultado.
Os dois modos, e qual usar
Modo interno
A instância do n8n lança o runner como processo filho. A documentação classifica esse modo como inseguro por natureza: o runner roda com o mesmo usuário e no mesmo servidor que o n8n, então código que escape do isolamento tem o mesmo acesso que o n8n — incluindo credenciais armazenadas.
Recomendado apenas em instâncias isoladas, sem dado sensível.
Modo externo
Um aplicativo lançador cria os runners sob demanda e gerencia o ciclo de vida deles. Na prática, isso significa rodar um contêiner adicional ao lado do n8n, com a imagem n8nio/runners, que traz o lançador e os executores de JavaScript e Python. Esse contêiner é independente da instância do n8n.
É o modo recomendado para produção e para qualquer instância com dado sensível.
A documentação é explícita quanto ao critério: economizar em hospedagem pulando o modo externo só é um compromisso razoável em instâncias isoladas que contenham apenas dados confiáveis ou fictícios. Se há credencial de cliente na instância, modo externo não é opcional.
A configuração de referência
O trecho abaixo vem da documentação oficial. Duas exigências antes de copiar: a versão da imagem n8nio/runners precisa ser a mesma da imagem n8nio/n8n, e a versão do n8n precisa ser 1.111.0 ou superior.
services:
n8n:
image: n8nio/n8n:1.111.0
container_name: n8n-main
environment:
- N8N_RUNNERS_ENABLED=true
- N8N_RUNNERS_MODE=external
- N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0
- N8N_RUNNERS_AUTH_TOKEN=your-secret-here
- N8N_NATIVE_PYTHON_RUNNER=true
ports:
- "5678:5678"O que cada variável faz:
| Variável | Função |
|---|---|
N8N_RUNNERS_ENABLED | Liga o mecanismo |
N8N_RUNNERS_MODE | internal ou external |
N8N_RUNNERS_BROKER_LISTEN_ADDRESS | Onde o broker escuta os runners |
N8N_RUNNERS_AUTH_TOKEN | Segredo compartilhado entre broker e runner |
N8N_NATIVE_PYTHON_RUNNER | Habilita Python no node Code |
Repare na última: é ela que libera Python no node Code, além de JavaScript. Se você vem de análise de dados, isso muda bastante o que é confortável escrever dentro de um fluxo.
O detalhe que quebra quem usa modo de fila
Aqui está a pegadinha que derruba instalação escalada, e ela merece atenção: quando você roda o n8n em modo de fila, com vários processos trabalhadores, cada trabalhador precisa do seu próprio contêiner de runners. Não existe um contêiner compartilhado entre todos.
Há um segundo caso, menos comum: se a execução manual não estiver sendo repassada aos trabalhadores, a instância principal também executa código e precisa do contêiner dela. Vale lembrar que rodar sem esse repasse não é recomendado em produção.
Esquecer isso produz um sintoma confuso: o fluxo funciona ao ser testado na tela e falha quando roda sozinho — porque o trabalhador que o executou não tinha runner.
O que fazer na sua instância
Confira a versão. Abaixo da 1.111.0, o modo externo não está disponível.
Se há dado de cliente, use modo externo. Não é ajuste fino de desempenho; é isolamento de credenciais.
Se algum Code parou de funcionar depois de atualizar, verifique se ele lia variável de ambiente. Esse acesso agora é bloqueado.
Em modo de fila, um contêiner de runners por trabalhador.
Mantenha as versões casadas entre a imagem do n8n e a dos runners ao atualizar.
Resumindo: Task Runners isolam o código do node Code do resto do n8n. Modo interno é conveniente e inseguro; modo externo é um contêiner a mais e a única opção defensável quando há credencial de terceiros na instância.
Esta aula faz parte do Curso de n8n do zero ao avançado, com todas as aulas em portugues.
Perguntas frequentes
O que são Task Runners no n8n?
São o mecanismo que executa o código JavaScript e Python do node Code de forma isolada do processo do n8n. Segundo a documentação, eles são a única camada de isolamento entre o código escrito nos fluxos e a instância — sem eles, quem edita um fluxo pode potencialmente acessar banco, credenciais e chave de criptografia.
Qual a diferença entre modo interno e externo?
No interno, o n8n lança o runner como processo filho, com o mesmo usuário e no mesmo servidor — inseguro por natureza. No externo, um lançador cria os runners em um contêiner independente ao lado do n8n, e é o modo recomendado para produção e para qualquer instância com dado sensível.
Por que meu node Code parou de ler variáveis de ambiente?
Porque o acesso às variáveis de ambiente do sistema passa a ser bloqueado por padrão quando o código roda isolado. É a proteção funcionando como deveria. Código que dependia disso precisa receber os valores por outro caminho.
Preciso de um contêiner de runners para cada trabalhador?
Sim, quando a instância roda em modo de fila: cada trabalhador precisa do seu próprio contêiner de runners. Esquecer isso gera um sintoma confuso, em que o fluxo funciona no teste manual e falha quando executa sozinho.
Qual versão do n8n é necessária?
O modo externo exige n8n 1.111.0 ou superior, e a versão da imagem de runners precisa ser exatamente a mesma da imagem do n8n. Versões diferentes entre as duas imagens causam falha na comunicação.
Como habilitar Python no node Code?
Pela variável N8N_NATIVE_PYTHON_RUNNER, definida como verdadeira na configuração da instância. Com ela ativa, o node Code passa a aceitar Python além de JavaScript.
