Por que uma variável no meu arquivo .env não tem efeito?

O arquivo do Compose só repassa ao app as variáveis listadas no bloco environment do serviço nodaro. Adicione qualquer outra variável a esse bloco no docker-compose.community.yml e depois rode docker compose up -d.

Quais variáveis de ambiente são obrigatórias?

Nenhuma na stack do Compose incluída, que as define ou as gera. Fora dela, a API se recusa a iniciar sem SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY e um INTERNAL_ORCHESTRATOR_SECRET de pelo menos 32 caracteres.

Preciso reiniciar depois de alterar uma variável?

Sim. O Nodaro lê o ambiente na inicialização, então rode docker compose up -d para recriar o contêiner com os novos valores. As chaves de provedor coladas em /setup são a exceção e passam a valer sem reinicialização.

Como mudo o idioma padrão da minha instalação?

Defina DEFAULT_LOCALE, por exemplo DEFAULT_LOCALE=de, e reinicie. Um novo visitante começa nesse idioma. A escolha que o próprio usuário salvou sempre prevalece, e um valor desconhecido volta ao idioma do navegador.

Como adiciono os meus próprios tutoriais a uma instalação self-hosted?

Coloque cada pacote de tutoriais em um diretório com um manifest.json e um arquivo JSON por tutorial, monte-o no contêiner e liste os diretórios em NODARO_TUTORIAL_PACKS. Reinicie para carregá-los.

Variáveis de ambiente do Nodaro: todas as configurações de self-hosting com o padrão de cada uma

Todas as variáveis de ambiente de um Nodaro self-hosted, por finalidade, com o padrão, se o .env pode defini-las na stack do Compose e o que elas mudam.

Esta página é a referência de configuração de um Nodaro self-hosted: todas as variáveis de ambiente que os operadores definem, agrupadas por finalidade, com o padrão de cada uma. Na stack do Compose incluída, toda variável tem um padrão que funciona, então você só define o que quer mudar. As variáveis que só se aplicam ao Nodaro Cloud não estão listadas.

Como definir uma variável

Na stack do Compose, você define uma variável em um destes dois lugares:

No .env, ao lado do docker-compose.community.yml. Isso funciona para as variáveis que o arquivo do Compose repassa ao app. Nas tabelas abaixo, a coluna .env mostra Sim para elas.
No arquivo do Compose, para todas as outras variáveis. Adicione a variável em environment: do serviço nodaro:

  nodaro:
    environment:
      # ...the variables already listed...
      MCP_ENABLED: "true"
      MCP_PUBLIC_URL: https://mcp.nodaro.example.com

Depois, aplique a alteração:

docker compose -f docker-compose.community.yml up -d

O Nodaro lê o ambiente na inicialização. A única exceção são as chaves de provedor que você cola em /setup, que passam a valer na hora. Fora da stack do Compose, defina as variáveis nas configurações de ambiente da sua plataforma.

Obrigatórias fora da stack do Compose: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY e INTERNAL_ORCHESTRATOR_SECRET. Sem elas, a API se recusa a iniciar e lista as variáveis ausentes ou inválidas.

Instância

Variável	Padrão	.env	O que faz
`EDITION`	`community`	Não	`community`, `business` ou `cloud`. O arquivo do Compose a fixa em `community`. Veja Edições e perfis de superfície.
`PUBLIC_URL`	`http://localhost:3000`	Sim	A origem pública da instalação: callbacks de login e de OAuth, URLs de mídia e a verificação de CORS.
`PUBLIC_URL_SAME_ORIGIN`	não definida	Não	`true` passa ao navegador o endereço de API `/` em vez de `PUBLIC_URL`, de modo que os streams ficam no nome de host que o visitante abriu. Para instalações que respondem em vários nomes de host. Só o valor exato `true` ativa esse comportamento.
`CORS_ORIGIN`	vazia	Sim	Origens extras do navegador, separadas por vírgula. `PUBLIC_URL` é sempre permitida. Nesses hosts, o redirecionamento do SSO para a página de destino é relativo.
`DEFAULT_LOCALE`	vazia (o idioma do navegador)	Sim	O idioma em que um novo visitante começa. Veja Idioma padrão.
`NODARO_SURFACE_PROFILE`	vazia (a interface completa)	Sim	Restringe a interface de uma instalação Business. Veja Perfis de superfície.
`NODARO_TUTORIAL_PACKS`	vazia (só os tutoriais nativos)	Sim	Diretórios de pacotes de tutoriais extras, separados por vírgula. Veja Pacotes de tutoriais.
`RUNTIME_ENV`	`local`	Não	Dá nome à instalação quando duas instalações compartilham um banco de dados, mas não um Redis. Veja Escalonamento. No Railway, `RAILWAY_ENVIRONMENT_NAME` define essa variável.
`PORT`, `HOST`	`8000`, `0.0.0.0`	Não	Onde a API escuta. Na imagem, a API escuta na porta `9000`, atrás do servidor web na `3000`.
`NODE_ENV`	`development`	Não	`production` em todas as imagens.

Segredos

Variável	Padrão	.env	O que faz
`INTERNAL_ORCHESTRATOR_SECRET`	Gerado na inicialização, na stack do Compose	Sim	Autentica o orquestrador na API. Pelo menos 32 caracteres. Obrigatório fora da stack do Compose.
`NODARO_ENCRYPTION_KEY`	Gerada na primeira inicialização, na stack do Compose, e guardada no volume `app-data`	Sim	Uma chave hexadecimal de 64 caracteres que criptografa as credenciais armazenadas: as chaves de provedor coladas, os tokens de login das redes sociais e as credenciais HTTP salvas para o nó Saída de webhook (Webhook Output).
`SOCIAL_ENCRYPTION_KEY`	vazia	Sim	O nome antigo de `NODARO_ENCRYPTION_KEY`. Qualquer um dos dois funciona.

Gere um segredo com openssl rand -hex 32. Faça backup da chave de criptografia junto com o banco de dados: veja Backup e restauração.

Variável	Padrão	.env	O que faz
`SUPABASE_URL`	`http://localhost:3000/supabase` na stack do Compose	Sim	A URL do Supabase que a API usa. Obrigatória fora da stack do Compose.
`SUPABASE_SERVICE_ROLE_KEY`	Uma chave padrão pública, na stack do Compose	Sim	A chave service-role que a API usa. Obrigatória fora da stack do Compose.
`SUPABASE_ANON_KEY`	Uma chave padrão pública, na stack do Compose	Sim	A chave anon entregue ao navegador e ao serviço de login.
`FRONTEND_SUPABASE_URL`	`PUBLIC_URL/supabase` na stack incluída	Sim	A URL do Supabase que o navegador usa, gravada em `/config.js` na inicialização. Defina-a quando usar um projeto gerenciado no Supabase.
`SUPABASE_JWT_SECRET`	Um segredo padrão público	Sim	O segredo que assina as chaves anon e service-role na stack incluída. Gere os três valores com `node tools/generate-selfhost-keys.mjs`.
`POSTGRES_PASSWORD`	`nodaro-postgres-pw`	Sim	A senha do banco de dados incluído. As senhas das roles internas só a acompanham na primeira inicialização do banco de dados.
`DATABASE_URL`	`postgres://postgres:nodaro-postgres-pw@db:5432/postgres`	Sim	Uma URL direta do Postgres, usada só para aplicar as migrações na inicialização. Mantenha a senha dela igual à de `POSTGRES_PASSWORD`.
`RUN_MIGRATIONS_ON_BOOT`	`false`; `true` na stack do Compose	Sim	Aplica `supabase/migrations/` antes de a API iniciar. Defina `false` com um projeto gerenciado no Supabase.
`SUPABASE_MANAGED_PROXY`	não definida	Não	`true` serve um projeto gerenciado no Supabase pela própria origem do app. Veja Banco de dados.
`SUPABASE_PROXY_UPSTREAM`	não definida	Não	A origem do projeto gerenciado, sem caminho, para o proxy acima.

Filas

Variável	Padrão	.env	O que faz
`REDIS_URL`	`redis://localhost:6379`; `redis://redis:6379` na stack do Compose	Não	O Redis das filas e dos caches compartilhados. Uma URL de cluster ou de Sentinel também funciona.

Armazenamento

Variável	Padrão	.env	O que faz
`R2_ENDPOINT`	`http://minio:9000` na stack do Compose	Sim	A URL da API S3 do armazenamento. Na stack do Compose, um valor vazio volta ao MinIO.
`R2_FORCE_PATH_STYLE`	`true` na stack do Compose	Sim	Endereçamento no estilo de caminho (path-style), que a maioria dos armazenamentos self-hosted exige.
`R2_ACCOUNT_ID`	vazia	Sim	O ID da conta do Cloudflare. Fora da stack do Compose, o endpoint do R2 é derivado dele quando `R2_ENDPOINT` não está definida.
`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`	As credenciais do MinIO incluído	Sim	As credenciais do armazenamento. Na stack do Compose, elas também são as credenciais root do MinIO.
`R2_BUCKET_NAME`	`nodaro-assets` na stack do Compose	Sim	O bucket. Fora da stack do Compose, o padrão é `scenenode-assets`, então sempre defina essa variável.
`R2_PUBLIC_URL`	`http://localhost:3000/storage/nodaro-assets` na stack do Compose	Sim	A URL pública do bucket.
`R2_REGION`	`auto`	Sim	A região S3. Defina uma região real para a AWS, o DigitalOcean Spaces (`nyc3` e outras) e um Supabase local (`local`).
`STORAGE_OBJECT_ACL`	vazia (sem cabeçalho de ACL)	Sim	Uma ACL pré-configurada em cada objeto enviado, para armazenamentos que recusam uma política de bucket. Veja Instalação.
`R2_PUBLIC_FALLBACK_DOMAIN`	vazia	Não	Um segundo host público para a mídia, por exemplo o endereço `r2.dev` direto ao lado de um domínio de CDN.
`R2_SHARED_WITH_RELAY_TARGET`	`false`	Não	`true` só quando `R2_PUBLIC_URL` aponta para o mesmo bucket em que o seu host do Nodaro Cloud grava. Veja Conectar ao Nodaro Cloud.

Provedores de modelos

Cada uma destas chaves também pode ser colada em /setup. Uma chave definida no ambiente tem prioridade. Veja Chaves de provedor.

Variável	Padrão	.env	O que habilita
`NODARO_API_KEY`	vazia	Sim	O Nodaro Cloud como provedor, com um token de API pessoal.
`KIE_API_KEY`	vazia	Sim	A maior cobertura de modelos de mídia e de texto.
`KIE_API_BASE_URL`	O host de API do próprio provedor	Sim	Envia o tráfego desse provedor pelo seu próprio proxy. Também redireciona o tráfego de texto do Claude e do Gemini que roda com a `KIE_API_KEY`.
`REPLICATE_API_TOKEN`	vazia	Sim	Um catálogo alternativo, incluindo os modelos Flux 2.
`ANTHROPIC_API_KEY`	vazia	Sim	O Claude, diretamente, para os nós de texto.
`GEMINI_API_KEY`	vazia	Sim	O Gemini, diretamente. Veja Modelos Gemini.
`ELEVENLABS_API_KEY`	vazia	Sim	Fala, vozes e dublagem.
`ELEVENLABS_BASE_URL`	`https://api.elevenlabs.io`	Sim	Envia o tráfego da ElevenLabs pelo seu próprio proxy.
`FAL_KEY`	vazia	Sim	Modelos como o Sync Lipsync v3.
`HEYGEN_API_KEY`	vazia	Sim	Avatar de IA (AI Avatar) e Avatar cinematográfico (Cinematic Avatar).
`BEEBLE_API_KEY`	vazia	Sim	Reiluminar e trocar (Relight & Switch).
`APIFY_API_TOKEN`	vazia	Sim	Extrair da web (Web Scrape).
`HEYGEN_CATALOG_REFRESH_HOURS`	`24`	Não	A frequência com que a lista compartilhada de avatares e vozes da HeyGen é atualizada.

Conexão com o Nodaro Cloud

Variável	Padrão	.env	O que faz
`NODARO_CLOUD_URL`	`https://app.nodaro.ai`	Sim	O host do Nodaro Cloud em que o botão Conectar o nodaro.ai faz o registro, e para onde vão as chamadas feitas com a `NODARO_API_KEY`. Mude essa variável só quando a sua instalação pertencer a uma implantação dedicada do Nodaro. Ela é lida na inicialização.

NODARO_API_KEY e R2_SHARED_WITH_RELAY_TARGET também fazem parte da conexão. Veja Conectar ao Nodaro Cloud.

Workers e desempenho

Variável	Padrão	.env	O que faz
`MAX_CONCURRENT_NODES_PER_EXECUTION`	`6`, no máximo `20`	Não	Quantos nós uma execução de workflow pode executar ao mesmo tempo.
`VIDEO_WORKER_CONCURRENCY`	`50`	Não	Jobs em paralelo no worker de mídia, que passa a maior parte do tempo esperando os provedores.
`ORCHESTRATOR_CONCURRENCY`	`20`	Não	Jobs em paralelo no orquestrador.
`RENDER_WORKER_CONCURRENCY`	`2`, no máximo `10`	Não	Renderizações em paralelo. Cada renderização roda um Chrome headless.
`REMOTION_CONCURRENCY`	`2` para cenas 3D; metade dos núcleos da CPU para as outras renderizações	Não	Abas do navegador por renderização. Um valor que você define vale para os dois casos. Mantenha-o baixo quando vários jobs 3D são executados ao mesmo tempo: cada aba WebGL acrescenta threads e conta para o limite de processos do contêiner.
`FFMPEG_CONCURRENCY`	`4`, no máximo `32`	Não	Processos do ffmpeg ao mesmo tempo, somando todos os nós de edição de vídeo e de áudio.
`RAILWAY_DEPLOYMENT_DRAINING_SECONDS`	não definida	Não	Só no Railway: o tempo entre o sinal de parada e a parada forçada de um contêiner substituído. O worker de mídia drena durante esse tempo menos 5 segundos. Sem a variável, ele drena por 25 segundos.

Leia Escalonamento antes de aumentar esses valores.

Editores

Variável	Padrão	.env	O que faz
`FREECUT_URL`	vazia (o editor hospedado)	Sim	O editor de vídeo por trás de Editar no NodarCut, no canvas, e de Editar, em um resultado de vídeo de um app. `off` desliga o editor: os botões continuam, mas nenhum editor abre.
`AUDIOMASS_URL`	vazia (sem editor de áudio)	Sim	O editor de áudio por trás de Editar, em um resultado de áudio de um app. `off` tem o mesmo efeito que um valor vazio.

Veja Editores de vídeo e de áudio.

Atualizações

Variável	Padrão	.env	O que faz
`NODARO_IMAGE`	`ghcr.io/nodaroai/nodaro-community:latest`	Sim	A imagem do app que o arquivo do Compose roda. Fixe aqui uma tag de versão.
`NODARO_UPDATE_CHECK`	ativada	Não	`off` desliga a verificação diária de atualizações: nenhuma requisição sai da instalação. Para instalações isoladas da internet (air-gapped).
`NODARO_UPDATE_CHECK_TOKEN`	vazia (anônima)	Não	Um token do GitHub para a verificação de atualizações, sem escopos.

Veja Atualização.

MCP

Variável	Padrão	.env	O que faz
`MCP_ENABLED`	desativado	Não	`true` ou `1` serve o endpoint MCP.
`MCP_PUBLIC_URL`	vazia (o host MCP do Nodaro Cloud)	Não	O endereço público do seu host MCP.
`MCP_DYNAMIC_REGISTRATION`	`allowlist`	Não	O registro dinâmico de clientes MCP: `allowlist`, `open` ou `off`.
`MCP_DCR_ALLOWLIST`	14 clientes conhecidos	Não	Os nomes de cliente que podem se registrar no modo `allowlist`.

Veja MCP.

Variável	Padrão	.env	O que faz
`EXTERNAL_SSO_PROVIDERS`	vazia (SSO desativado)	Não	Provedores de identidade confiáveis, como JSON inline ou `@/path/to/file.json`. Um valor malformado interrompe a inicialização.
`EXTERNAL_SSO_LINK_EXISTING`	`false`	Não	Se o login único (SSO) pode ser vinculado a uma conta local existente.
`PLATFORM_OWNER_EMAIL`	vazia	Não	Business: a conta do proprietário, cuja função nenhum outro administrador pode alterar.

Veja Login único (SSO) e Primeiro usuário e administrador.

Integrações

Variável	Padrão	.env	O que faz
`FIGMA_PLUGIN_OAUTH_CLIENT_ID`	vazia (conexão do plugin desativada)	Não	O ID do cliente do app de desenvolvedor pelo qual o plugin do Figma se conecta.
Variáveis das redes sociais	vazias	Não	Veja Apps das redes sociais.

Para o plugin do Figma, registre um app de desenvolvedor na sua instalação com <PUBLIC_URL>/v1/oauth/plugin/callback como URI de redirecionamento e os escopos jobs:read, assets:read, assets:write e credits:read. Depois, defina aqui o ID do cliente dele. Quando a variável está vazia, as rotas de conexão do plugin respondem 503, e nada mais muda. Veja Apps OAuth.

Configurações fixadas na build

Estas configurações são fixadas quando a imagem é compilada. Altere-as em build: args: do arquivo do Compose e recompile.

Argumento de build	Padrão	O que faz
`VITE_EDITION`	`community` no arquivo do Compose	A edição que o editor mostra. A build recusa um valor vazio ou desconhecido.
`VITE_STUDIO_URL`	`https://studio.nodaro.ai`	O endereço dos links Abrir no Studio.
`VITE_PERSON_URL`	`https://person.nodaro.ai`	O endereço do cartão Abrir Person da tela inicial.

Editores de vídeo e de áudio

Editar no NodarCut, em um resultado de vídeo no canvas, e Editar, em um resultado de vídeo de um app, abrem o editor de vídeo NodarCut. Editar, em um resultado de áudio de um app, abre o editor AudioMass. A sua mídia não vai para o servidor do editor: o app lê o arquivo do seu próprio armazenamento e o entrega ao editor dentro do navegador. A edição e a exportação acontecem ali.

Vídeo. Com FREECUT_URL vazia, o editor é carregado de freecut.nodaro.ai, que só permite ser incorporado a partir de http://localhost:3000. Em outra origem, como um endereço da LAN ou um domínio, o navegador o recusa, e o painel explica o motivo. Abra uma issue no GitHub com a URL que você serve para que ela seja permitida, ou rode o seu próprio FreeCut. O FreeCut é público, tem licença MIT e inclui um Dockerfile. Depois, defina FREECUT_URL=https://freecut.example.internal.
Áudio. Não existe um AudioMass público hospedado, então, até você configurá-lo, Editar, em um resultado de áudio, não abre nenhum editor. Na aba Apresentar, não faz nada, e fora do editor, mostra um painel que explica o que definir. Rode o fork do Nodaro, o AudioMass, que aceita a transferência dentro do navegador que falta no AudioMass original. Depois, defina AUDIOMASS_URL=https://audiomass.example.internal.

Reinicie a stack depois de uma alteração. Não é preciso recompilar.

Idioma padrão

DEFAULT_LOCALE define o idioma em que um novo visitante começa. Os valores são he, ar, de, fr, es, hi, ja, ko, pt-BR, ru, zh-CN e en. A escolha que o próprio usuário salvou sempre prevalece. Um valor vazio, em branco ou desconhecido volta ao idioma do navegador do visitante. Reinicie para aplicar. Veja Idiomas.

Pacotes de tutoriais

Uma instalação self-hosted pode adicionar os próprios tutoriais ao conjunto nativo, sem recompilar. Cada pacote é um diretório:

manifest.json — o name do pacote e as categories que os tutoriais dele usam, cada uma com um slug, um name e, opcionalmente, um sortOrder e uma description. Chaves opcionais: locale, version, forbiddenPromptTerms e creatorDisplayName, o nome do autor mostrado em todos os cartões do pacote.
Um arquivo *.json por tutorial — um snapshot de workflow com os nós, as conexões e os resultados já prontos, para que um clone abra mostrando a execução concluída. Dados opcionais do cartão: estimatedCredits, nodeTypesUsed e providersUsed, para os chips do cartão, um creatorDisplayName por tutorial e listedIn. listedIn é ["tutorial"] para a aba Tutoriais, o padrão, ou ["marketplace"] para o marketplace de templates. Ele só vale no primeiro seed.

Toda mídia que um tutorial usa precisa ser uma URL https:// pública. A categoria de cada tutorial precisa ser declarada no manifesto, e ela é criada na primeira inicialização.

Monte os diretórios dos pacotes no contêiner como somente leitura e liste os caminhos deles dentro do contêiner:

  nodaro:
    volumes:
      - ./tutorials/acme:/data/tutorials/acme:ro

NODARO_TUTORIAL_PACKS=/data/tutorials/acme

Os pacotes só adicionam tutoriais; eles nunca mudam os nativos. Um pacote que falha na validação é ignorado por inteiro e registrado no log. A validação falha com um JSON inválido, uma categoria não declarada, uma URL de mídia que não é pública ou um slug que colide com um tutorial existente. Reinicie o contêiner para carregar um pacote alterado.

A publicação em redes sociais funciona por rede. Uma rede fica disponível assim que as credenciais do app OAuth dela são definidas. Sem elas, a rede continua aparecendo em Configurações › Integrações como indisponível, com os nomes das variáveis que faltam.

Rede	Variáveis
Instagram	`META_APP_ID`, `META_APP_SECRET`. Opcional: `META_INSTAGRAM_CONFIG_ID`, para o Facebook Login for Business.
Instagram, sem uma Página do Facebook	`INSTAGRAM_APP_ID`, `INSTAGRAM_APP_SECRET`. A Meta emite essas credenciais separadamente do app do Facebook. Os tokens se renovam sozinhos, a cada cerca de 60 dias.
Facebook	`META_APP_ID`, `META_APP_SECRET`. Opcional: `META_FACEBOOK_CONFIG_ID`.
TikTok	`TIKTOK_CLIENT_KEY`, `TIKTOK_CLIENT_SECRET`
YouTube	`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
LinkedIn	`LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`
X	`X_CLIENT_ID`, `X_CLIENT_SECRET`
Reddit	`REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET`
Pinterest	`PINTEREST_CLIENT_ID`, `PINTEREST_CLIENT_SECRET`
Discord	`DISCORD_CLIENT_ID`, `DISCORD_CLIENT_SECRET`, `DISCORD_BOT_TOKEN`
Twitch	`TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET`
Threads	`THREADS_APP_ID`, `THREADS_APP_SECRET`
Mastodon	`MASTODON_CLIENT_ID`, `MASTODON_CLIENT_SECRET`. Opcional: `MASTODON_URL`, com o padrão `mastodon.social`.
Telegram	Nenhuma: os usuários colam o próprio token de bot.
Bluesky	Nenhuma: os usuários se conectam com um handle e uma senha de app.
Dev.to, Hashnode, Medium	Nenhuma: os usuários se conectam com a própria chave de API ou o próprio token.
WordPress	Nenhuma: os usuários se conectam com a URL do site e uma senha de aplicativo.
Lemmy	Nenhuma: os usuários se conectam com uma instância, um login e uma comunidade.

Todo app OAuth precisa permitir a URI de redirecionamento https://<your-domain>/v1/social/callback/<network>. Quando um login do Facebook ou do Instagram gerencia mais de uma Página ou conta, a janela de conexão pergunta ao usuário qual delas conectar. Veja Publicar nas redes sociais.

Configuração