Referência de configuração do servidor

Este guia lista as configurações do servidor que você pode mudar com variáveis de ambiente, que são configurações que o servidor lê de um arquivo de texto simples chamado .env. Marinara funciona sem nenhuma configuração. A maioria das pessoas só precisa dela para deixar outros dispositivos se conectarem, proteger um servidor compartilhado, mudar a pasta de dados de lugar, aumentar o detalhamento do log ou dar mais tempo para tarefas lentas.

As suas contas de IA, os personagens e as opções de chat são definidos dentro do aplicativo. Para adicionar uma conta de IA, veja Conectando a um provedor de IA.

Editar o arquivo .env

Marinara cria um arquivo .env vazio na primeira vez que inicia. Cada linha segue o formato KEY=value. As linhas que começam com # são comentários.

1. Abra o arquivo .env.example na mesma pasta. Ele lista todas as configurações com o valor padrão.
2. Copie a linha que você quer para o arquivo .env.
3. Mude o valor depois do = e salve o arquivo.

PORT=8080
BASIC_AUTH_USER=alice
BASIC_AUTH_PASS=correct-horse-battery-staple

O arquivo .env guarda dados, não é um script de shell. Marinara não executa $, $(...) nem outra sintaxe de shell em um valor. Um valor já definido no ambiente do inicializador tem prioridade sobre a mesma entrada do .env.

O servidor lê o .env não importa como você o inicia. Os inicializadores (start.bat, start.sh, start-termux.sh) também definem HOST=0.0.0.0, para que outros dispositivos se conectem, e abrem o navegador quando o servidor fica pronto. AUTO_OPEN_BROWSER=false desativa essa abertura. Com o pnpm start puro, o servidor escuta só neste computador, a não ser que você defina HOST.

Reiniciar ou recarregar na hora

Marinara observa o .env enquanto está em execução. A maioria das configurações passa a valer quase na hora, sem reiniciar. O log mostra uma linha [env-watcher] a cada mudança. Se a observação não conseguir começar, o servidor confere o arquivo a cada 30 segundos e avisa isso no log.

Se as suas edições não forem detectadas, por exemplo quando você edita o arquivo de outra máquina ou dentro de um bind mount de contêiner, defina MARINARA_ENV_WATCH=poll. Para desligar a observação, defina MARINARA_ENV_WATCH=0. As duas são opções avançadas.

Estas configurações só são lidas na inicialização. Mudar uma delas exige reinício, e o log avisa você:

• PORT, HOST, SSL_CERT e SSL_KEY
• DATA_DIR, FILE_STORAGE_DIR, ENCRYPTION_KEY e MARINARA_EAGER_STORAGE
• MARINARA_ENV_FILE, MARINARA_ENV_WATCH e TZ
• AUTO_OPEN_BROWSER e AUTO_CREATE_DEFAULT_CONNECTION
• LOG_DISABLE_REQUEST_LOGGING e LOG_FORMAT
• STORAGE_CACHE_WINDOWS_BOOT_ID, SHUTDOWN_WINDOWS_CONSOLE_SIGNALS e SHUTDOWN_FORCE_EXIT_ON_REPEAT
• As configurações de tempo limite e de consulta de imagem, vídeo, sprite e ComfyUI: IMAGE_GEN_TIMEOUT_MS, IMAGE_GEN_MAX_RESPONSE_BYTES, VIDEO_GEN_TIMEOUT_MS, VIDEO_GEN_MAX_RESPONSE_BYTES, SPRITE_GENERATION_TIMEOUT_MS, SPRITE_ANIMATED_FFMPEG_TIMEOUT_MS, COMFYUI_GEN_TIMEOUT e as quatro configurações *_VIDEO_POLL_INTERVAL_MS

Os inicializadores leem AUTO_UPDATE_ENABLED antes de o servidor iniciar, então uma mudança vale a partir do próximo início e o log não avisa sobre ela.

As configurações de controle de acesso e os segredos (BASIC_AUTH_USER, BASIC_AUTH_PASS, IP_ALLOWLIST, ADMIN_SECRET, CSRF_TRUSTED_ORIGINS) não exigem reinício.

Controle de acesso

O controle de acesso decide quem pode alcançar um servidor em execução. Para o passo a passo e exemplos, veja Acesso remoto: login e lista de IPs permitidos.

Você também pode definir o login sem o .env: use Settings → Advanced → Access (Configurações → Avançado → Acesso) em um navegador que já está conectado, ou o código de configuração de uso único do log do servidor. O servidor imprime esse código somente enquanto nenhum login está definido e ele escuta além do loopback. O login é salvo em DATA_DIR/.remote-login.json. node scripts/reset-login.mjs (executado na pasta do Marinara) remove o login e desconecta todos os navegadores. Um login no .env tem prioridade. Mudar ou remover o login exige a senha atual. Para proxies de login, veja Proxies de login (forward auth).

Termos usados adiante:

• Loopback: o próprio computador em que o servidor roda, em 127.0.0.1 ou localhost.
• Faixa CIDR: uma forma curta de escrever um bloco de endereços IP, como 192.168.1.0/24.
• Basic Auth: um nome de usuário e uma senha enviados a cada requisição. Scripts e clientes de API usam esse método, e os navegadores usam a página /login. As credenciais são apenas codificadas, não criptografadas, então use HTTPS em um servidor público.

Sem nenhum login definido, o servidor aceita só origens confiáveis: o loopback, os endereços em IP_ALLOWLIST, o Tailscale e o tráfego da ponte do Docker no mesmo host. Todo o resto, inclusive a sua rede doméstica, recebe 403 Forbidden. Para que outros dispositivos consigam se conectar, o servidor precisa se associar a um endereço acessível: defina HOST=0.0.0.0.

Aviso: uma faixa pública ampla em IP_ALLOWLIST, como 0.0.0.0/0, pode deixar clientes da internet entrarem sem login. Liste apenas endereços em que você confia.

Armazenamento

Gere uma chave de criptografia e cole-a em ENCRYPTION_KEY:

openssl rand -hex 32

Marinara guarda os seus dados como arquivos JSON simples, então você pode copiar e ler os backups. Para saber o que cada pasta guarda, veja Onde o Marinara guarda os seus dados.

Níveis de log

LOG_LEVEL define quanto o servidor imprime. Ele esconde tudo o que fica abaixo do nível escolhido.

Em um terminal, o servidor imprime linhas legíveis. Em outros lugares, como os logs do Docker, um servidor de produção imprime linhas JSON. O inicializador do Termux pede linhas legíveis. O log do navegador é separado e não é controlado por LOG_LEVEL.

Tempos limite

Um tempo limite é o máximo que o servidor espera por uma tarefa lenta. Abra Settings → Advanced → Request timeouts (Configurações → Avançado → Tempos limite das requisições) para mudar, em segundos, os limites de texto, agentes, prompts de imagem do Game, imagens, vídeos, ComfyUI e embeddings. Limites maiores ajudam backends locais lentos. Eles não podem substituir um limite que o próprio serviço impõe. Para salvar, é preciso ter acesso de administração do servidor.

Essas configurações valem para todos os perfis e são salvas ao lado do .env ativo como .env.timeouts.json (ou <custom-env-path>.timeouts.json). Elas têm prioridade sobre as variáveis correspondentes sem editar o .env. Mudanças de texto, agentes, prompts de imagem do Game e embeddings valem para novas requisições. Mudanças de mídia e pacotes de agentes instalados exigem reinício. Para voltar às variáveis, exclua esse arquivo e reinicie.

Os valores são em milissegundos, salvo quando o nome diz outra coisa. Valores inválidos, zerados, negativos ou fora da faixa nos tempos limite validados de chat, de agente e de prompt de imagem do Game geram um aviso no log e usam o padrão. Para saber mais sobre as tarefas de vídeo, veja Vídeo de cena.

APIs privilegiadas (ADMIN_SECRET)

Ações destrutivas ou arriscadas, como fazer backup, limpar os dados, aplicar atualizações e instalar temas, exigem um segredo a mais, além das checagens normais de acesso. Você pode criar um em Settings → Advanced → Admin Access (Configurações → Avançado → Acesso de administrador) no próprio computador do servidor (veja Admin Access) ou definir um valor longo e aleatório no servidor:

ADMIN_SECRET=replace-this-with-a-long-random-secret

No próprio computador do servidor, essas ações costumam funcionar sem o segredo. Uma requisição que um proxy ou túnel nesse computador encaminha conta como remota, a não ser que REQUIRE_AUTH_FOR_LOOPBACK_PROXY=false. Requisições diretas de outro dispositivo precisam do segredo. Cole o mesmo valor em Settings → Advanced → Admin Access, e o aplicativo o envia por você. O ADMIN_SECRET do .env prevalece sobre um segredo criado no aplicativo. Sem segredo de administrador, as ações privilegiadas falham em todos os dispositivos, menos no próprio computador do servidor, e a mensagem de erro pede que você defina um. Os agentes instalados funcionam em qualquer dispositivo que entrou com o login; instalar, atualizar e remover agentes exige o segredo.

Liberação de endereços locais

Por padrão, as requisições de saída para serviços de IA, serviços de imagem e webhooks se recusam a alcançar endereços privados ou locais. Isso bloqueia o SSRF (server-side request forgery), em que uma requisição é enganada para alcançar um endereço interno. Os servidores de modelo em loopback continuam funcionando. Ative só a opção de que você precisa para um serviço hospedado por você em outra máquina da rede privada.

Para conectar um modelo local ou auto-hospedado, veja Conectar um modelo local ou auto-hospedado.

Chaves de recursos

Comportamentos opcionais do servidor, como repetir chamadas de provedor que falharam ou manter estáveis as seleções de grupos do lorebook, ficam em Settings → Advanced → Features (Configurações → Avançado → Recursos). Todos vêm desligados por padrão. Alguns têm uma variável que, quando definida, prevalece sobre a chave. Veja Chaves de recursos.

Avisos do Marinara

Os avisos são alertas curtos dos mantenedores, por exemplo sobre um problema de segurança ou um passo manual de que a sua versão precisa. Eles aparecem como um banner.

• Na inicialização e depois a cada hora, o servidor baixa um arquivo pequeno, notices.json, da branch notices do repositório do Marinara Engine. Ele guarda apenas os avisos que citam a sua versão. O seu navegador pede esses avisos ao seu próprio servidor uma vez quando a página carrega e depois a cada hora.
• Se um download falhar, o servidor mantém os avisos que já tem e a inicialização não atrasa.
• A requisição não envia dados sobre você, os seus chats ou as suas configurações. Só os mantenedores podem alterar a branch notices, e cada alteração passa por revisão.
• Um aviso é texto simples, com limite de tamanho. Os links só são mantidos quando apontam para https://github.com/Pasta-Devs/. Um aviso não pode instalar, executar nem alterar nada.
• Só você vê os avisos: no próprio computador do servidor, a partir de um endereço em IP_ALLOWLIST ou depois de entrar com o seu login. Os outros visitantes recebem uma lista vazia.

Para desativar os avisos, defina MARINARA_NOTICES_ENABLED=false.

Aviso: com os avisos desativados, Marinara não pode informar você sobre correções de segurança ou passos necessários. Acompanhe você mesmo as versões no GitHub.

Forks podem apontar MARINARA_NOTICES_URL para o próprio arquivo.

Multijogador opcional

O multijogador vem desativado por padrão. Ele permite que pessoas compartilhem uma sala privada de Conversation, Roleplay ou Game sem limite fixo de participantes. Cada convidado usa o próprio Marinara confiável. Os convidados não precisam de conta de IA. O anfitrião fornece as contas de IA e pode ler e guardar o conteúdo compartilhado. Enquanto qualquer uma das duas travas estiver desligada, Marinara não faz verificações de sessão, de certificado ou de pares em segundo plano.

1. Defina MULTIPLAYER_ENABLED=true no .env de cada Marinara participante e reinicie-o. Só o valor exato true funciona, e a recarga na hora não o aplica.
2. Abra Settings → Advanced → Multiplayer (Configurações → Avançado → Multijogador), leia o aviso e ative a configuração. Isso não abre uma porta de escuta nem entra em uma sala.
3. Para hospedar, use Create shared session (criar sessão compartilhada) ou Play together (jogar juntos) no fluxo de modo ou de configuração. Revise a configuração, o seu nome de exibição e o texto da persona que você compartilha. Um chat existente compartilha só as escolhas de configuração, nunca o histórico, as notas ou as memórias.
4. No anfitrião, defina SSL_CERT e SSL_KEY com um certificado válido para o hostname da sala e confiável para os convidados. Escolha um endereço HTTPS e uma porta separados para a sala, como https://room.example.org:7861. A ação de hospedar abre essa porta. Libere no firewall ou no roteador apenas a porta da sala. Não exponha a API normal do Marinara. Marinara não configura encaminhamento de portas, retransmissão nem desvio de certificado por você.
5. Defina uma senha de sala com pelo menos 12 caracteres, diferente das suas credenciais de administrador. Envie o convite com validade e a senha separadamente para pessoas em quem você confia. O convidado confere a impressão digital do hostname, o nome da sala e o texto da persona e então pede para entrar. O anfitrião aprova cada pedido em Players (jogadores) antes de qualquer histórico ser enviado.

Limites e comportamento:

• O TLS confere a cadeia do certificado e o hostname, além da impressão digital do certificado no convite, antes de enviar uma senha. Certificados autoassinados não são aceitos silenciosamente. Um certificado renovado exige um novo convite.
• Os convites expiram em 30 minutos. As sessões admitidas duram no máximo 12 horas. Substituir ou revogar invalida os convites não usados. Kick (expulsar) remove um convidado admitido.
• O anfitrião controla as respostas automáticas ou manuais, Pause/Resume (pausar/retomar) e Stop (parar). O limite padrão é de 100 turnos de geração coordenada por sessão hospedada. Um turno de grupo ou a configuração do Game pode fazer mais de uma chamada ao modelo. É um limite de turnos, não uma estimativa de preço.
• No Game, revise o grupo antes de Start Game (iniciar o jogo). Cada jogador necessário envia uma ação ou passa, e o GM resolve quando todos estão prontos. Um jogador desconectado continua necessário até voltar ou até o anfitrião passar a vez dele ou removê-lo. Rodadas pausadas ou interrompidas nunca repetem sozinhas uma requisição paga nem efeitos do mundo já gravados.
• Stop, Leave (sair), desativar a configuração e reiniciar o servidor encerram a sessão ativa. Um reinício nunca hospeda nem entra em uma sala sozinho.
• Ferramentas personalizadas e de pacotes e comandos inseguros continuam indisponíveis nas salas. Os convidados nunca executam um agendador nem comandos locais a partir do texto recebido. As agendas de Conversation usam o agendador do anfitrião.
• Novos jogadores e mudanças de persona valem a partir da rodada seguinte.
• As salas transmitem só texto de tamanho limitado. Não há transferência de arquivos, mídia, extensões ou pacotes. O wrapper nativo do Android não pode entrar.

Aviso: conecte-se apenas a pessoas em quem você confia e use o seu próprio cliente Marinara. Nunca instale um cliente, uma extensão ou um arquivo fornecido pelo anfitrião. O anfitrião pode ler o que você compartilha, e o conteúdo compartilhado pode ir para os serviços de IA dele. Conexões diretas revelam endereços de rede. Não compartilhe senhas, chaves de API ou informações pessoais. Saia na hora se algo parecer errado.

Para as restrições exatas e as plataformas testadas, veja o registro de compatibilidade e verificação. Para problemas, veja Solução de problemas.

Agentes e extensões

Instale os agentes oficiais opcionais dentro do aplicativo: Agents → Agent Organizer (Agentes → Organizador de agentes). Marinara escolhe o catálogo Pasta-Devs/Marinara-Agents que corresponde à sua versão principal.

• Atualizações: Marinara pergunta antes de baixar uma versão nova de um pacote instalado. Not now (agora não) mantém a versão atual e deixa o botão Update (atualizar) no Agent Organizer. Uma instalação nova não tem pacotes.
• Onde os pacotes ficam: DATA_DIR/capability-packages. Volumes do Docker, pastas de dados personalizadas, backups e atualizações normais preservam esses pacotes. Isso vale para o computador, o Docker e o Termux. O iOS e outros navegadores usam os pacotes do servidor que os hospeda.
• Uso de disco: Marinara mantém a versão atual e a anterior de cada pacote e exclui as versões mais antigas e as cópias temporárias em DATA_DIR/capability-runtime-snapshots. Os dados dos pacotes nunca são excluídos.
• Offline: os pacotes instalados continuam funcionando na versão em que estão quando o GitHub está inacessível, quando uma atualização é recusada ou quando a verificação falha.

Importação de agentes personalizados

Arquivos, pastas e repositórios externos de agentes vêm bloqueados. Para liberá-los, ative Allow custom Agent imports (permitir importações de agentes personalizados) em Settings → Advanced → Danger Zone (Configurações → Avançado → Zona de perigo). Isso não exige variável de ambiente. Os controles de importação ficam cinza até você ativar a opção.

Toda importação mostra primeiro as capacidades que o agente solicita. As permissões precisam de aprovação explícita. Funções embutidas e seleções de ferramentas não são importadas, o CSS gerado passa por limpeza e as ações de resultado são conferidas com base nas capacidades aprovadas. Desligar a trava faz os agentes importados pararem. Os agentes criados no Marinara e os pacotes oficiais não são afetados.

Repositórios de agentes personalizados

Os repositórios vêm desativados por padrão, porque os prompts e as ferramentas deles não passam por revisão. Defina ENABLE_CUSTOM_AGENT_REPOS=true, ative Allow custom Agent imports e abra Agents → Agent Organizer → Custom Sources (Agentes → Organizador de agentes → Fontes personalizadas) para pré-visualizar um repositório público do GitHub. Adicionar uma fonte e aplicar mudanças posteriores exigem confirmação. A sincronização é manual, e Marinara nunca clona nem consulta repositórios em segundo plano. Apenas URLs da raiz de repositórios do GitHub são aceitas.

Um repositório publica agentes, conjuntos de regras de Game Mode ou ambos. Na raiz:

• agents.json é um array no formato de agentes para download:

  [
    {
      "id": "continuity-helper",
      "name": "Continuity Helper",
      "description": "Checks recent turns for contradictions.",
      "phase": "post_processing",
      "enabledByDefault": false,
      "category": "writer",
      "defaultPromptTemplate": "Check {{messages}} for continuity errors."
    }
  ]

• rulesets contém um conjunto de regras por arquivo .json, até 32 arquivos de 512 KB. Só os arquivos que ficam diretamente dentro dessa pasta são lidos. A prévia lista o nome, a versão e a cobertura de cada conjunto. O texto de Game Master de um conjunto vai para o modelo em toda partida que o usa, então instale apenas conjuntos de pessoas em quem você confia.

Os conjuntos importados recebem o nome do dono do repositório, como alice/my-5e, então nunca tomam um nome oficial. Toda versão é mantida, e uma partida roda na versão exata com que começou. Se a mesma versão chegar com conteúdo diferente, Marinara mantém a instalada e avisa para você pedir ao autor que aumente o número da versão. Um arquivo que Marinara não consegue ler aparece na lista com o motivo e é ignorado.

Na sincronização, os valores remotos de prompt, configurações e ferramentas substituem os valores gerenciados pelo repositório que aparecem na prévia. As suas escolhas de conta e de imagens continuam locais. Se um agente sumir da origem, ele continua como um agente local comum e perde só o vínculo com o repositório. Remover uma fonte funciona do mesmo jeito, e os conjuntos de regras dela continuam instalados.

Agentes personalizados também podem ativar Previous output (saída anterior) em Context Sources para ler a própria última saída bem-sucedida. Com JSON context output (saída de contexto em JSON), retorne {"text":"main prompt content","agent-context":"private continuation context"}. Apenas text entra no prompt principal. Hide output as spoilers (ocultar a saída como spoiler) mantém as saídas salvas recolhidas. As regenerações deixam de fora o turno substituído, e mensagens excluídas ou swipes inativos não podem fornecer contexto.

Extensões externas

A importação de extensões de terceiros exige dois consentimentos. A variável de ambiente é a permissão de quem opera o servidor. O botão liga/desliga da Danger Zone é a aceitação do usuário.

1. Defina ENABLE_EXTERNAL_EXTENSIONS=true no .env.
2. Abra Settings → Advanced → Danger Zone, role para baixo até passar dos controles de exclusão de dados, leia o aviso e ative Allow third-party extension imports (permitir a importação de extensões de terceiros).

Então a seção External Extensions (extensões externas) aparece em Settings → Addons (Configurações → Complementos). Fechar qualquer uma das travas desativa os registros externos e para o código deles. Registros salvos manualmente, antigos, importados de um perfil ou de origem desconhecida contam como externos, então largar arquivos em uma pasta não burla as travas. Os rascunhos da Professor Mari não precisam de nenhuma das travas. Eles começam desativados e exigem aprovação do hash exato do código.

As Sandboxed Browser Extensions (extensões de navegador isoladas) são o padrão. Alguns pacotes mais antigos mostram Full page access (acesso à página inteira), porque precisam da página do Marinara. Esse modo roda o código aprovado na página do Marinara, com acesso ao conteúdo da página, ao armazenamento do navegador, às APIs de rede e à sua sessão. Ele só existe para as External Extensions com as duas travas abertas e exige uma confirmação de aviso separada. Recarregue a página depois de desativá-lo.

Referência completa das variáveis de ambiente

As tabelas anteriores cobrem controle de acesso, armazenamento, log, tempos limite, ações privilegiadas e liberação de endereços locais. As demais estão aqui.

Servidor e inicialização

O Schedule timezone usa por padrão o fuso horário do seu dispositivo. Você pode mudá-lo durante a configuração do Conversation, nas Chat Settings (configurações do chat) do Conversation ou no editor de agenda do personagem. É uma configuração global única, compartilhada por todos os chats de Conversation e sincronizada com os outros clientes do mesmo servidor.

Ferramentas de mídia e de sprite

Provedores de vídeo de cena

As contas de vídeo são configuradas dentro do aplicativo. Estas configurações apenas ajustam as tarefas. Os valores são em milissegundos.

Lorebooks

As duas vêm desligadas por padrão e valem na próxima geração depois de uma mudança no .env. Quando LOREBOOK_STABLE_GROUP_WINNERS está definida, ela prevalece sobre a chave Stable lorebook picks (seleções estáveis de lorebook) em Settings → Advanced → Features. Caso contrário, a chave decide. Veja Chaves de recursos.

scripts/compact-lorebook-scans.mjs aplica a mesma regra aos chats mais antigos. Pare o servidor primeiro. O script só faz uma simulação, a não ser que você passe --apply, e faz backup das duas tabelas de mensagens antes de gravar.

Robustez

Todas vêm desligadas por padrão, o que mantém o comportamento antigo. STORAGE_CACHE_WINDOWS_BOOT_ID, SHUTDOWN_WINDOWS_CONSOLE_SIGNALS e SHUTDOWN_FORCE_EXIT_ON_REPEAT exigem reinício. As demais valem depois de uma mudança no .env. Quando PROVIDER_RETRY_TRANSIENT_ERRORS está definida, ela prevalece sobre a chave Retry failed provider calls (repetir chamadas de provedor que falharam) em Settings → Advanced → Features. Caso contrário, a chave decide.

Integrações e extras

Sobre o Built-in model, veja Como configurar o Built-in model.

Proxy HTTP de saída

Algumas redes só chegam à internet por um proxy HTTP, por exemplo o v2rayN sem o modo TUN. Marinara pode enviar por esse proxy as requisições aos serviços de IA, aos serviços de imagem, aos servidores de embedding e ao catálogo de agentes. Defina estas variáveis no ambiente que inicia Marinara ou no .env e depois reinicie.

Guias relacionados

• Chaves de recursos
• Acesso remoto: login e lista de IPs permitidos
• Onde o Marinara guarda os seus dados
• Conectando a um provedor de IA
• Vídeo de cena
• Solução de problemas do Marinara Engine