Referencia de configuración del servidor

Esta guía lista los ajustes del servidor que puedes cambiar con variables de entorno, que son ajustes que el servidor lee de un archivo de texto plano llamado .env. Marinara funciona sin ninguna configuración. La mayoría de las personas solo la necesitan para dejar que otros dispositivos se conecten, proteger un servidor compartido, mover la carpeta de datos, subir el nivel de registro o dar más tiempo a los trabajos lentos.

Tus cuentas de IA, personajes y opciones de chat se configuran dentro de la app. Para añadir una cuenta de IA, consulta Conectarse a un proveedor de IA.

Editar el archivo .env

Marinara crea un .env vacío la primera vez que arranca. Cada línea es KEY=value. Las líneas que empiezan con # son comentarios.

1. Abre .env.example en la misma carpeta. Lista cada ajuste con su valor predeterminado.
2. Copia en .env la línea que quieras.
3. Cambia el valor después de = y guarda el archivo.

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

.env es datos, no un script de shell. Marinara no ejecuta $, $(...) ni otra sintaxis de shell en un valor. Un valor ya establecido en el entorno del lanzador tiene prioridad sobre la misma entrada de .env.

El servidor lee .env sin importar cómo lo inicies. Los lanzadores (start.bat, start.sh, start-termux.sh) también establecen HOST=0.0.0.0 para que otros dispositivos puedan conectarse, y abren tu navegador cuando el servidor está listo. AUTO_OPEN_BROWSER=false lo impide. Con pnpm start a secas, el servidor escucha solo en esta computadora a menos que establezcas HOST.

Reinicio o recarga en caliente

Marinara vigila .env mientras se ejecuta. La mayoría de los ajustes se aplican casi de inmediato, sin reinicio. El registro muestra una línea [env-watcher] por cada cambio. Si la vigilancia no puede iniciarse, el servidor comprueba el archivo cada 30 segundos y lo indica en el registro.

Si no se detectan tus cambios, por ejemplo cuando editas desde otra máquina o dentro del bind mount de un contenedor, establece MARINARA_ENV_WATCH=poll. Para desactivar la vigilancia, establece MARINARA_ENV_WATCH=0. Ambas son opciones avanzadas.

Estos ajustes solo se leen al arrancar. Cambiar uno necesita un reinicio, y el registro te lo advierte:

• PORT, HOST, SSL_CERT y SSL_KEY
• DATA_DIR, FILE_STORAGE_DIR, ENCRYPTION_KEY y MARINARA_EAGER_STORAGE
• MARINARA_ENV_FILE, MARINARA_ENV_WATCH y TZ
• AUTO_OPEN_BROWSER y AUTO_CREATE_DEFAULT_CONNECTION
• LOG_DISABLE_REQUEST_LOGGING y LOG_FORMAT
• STORAGE_CACHE_WINDOWS_BOOT_ID, SHUTDOWN_WINDOWS_CONSOLE_SIGNALS y SHUTDOWN_FORCE_EXIT_ON_REPEAT
• Los tiempos de espera y los ajustes de sondeo de imagen, video, sprite y 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 y los cuatro ajustes *_VIDEO_POLL_INTERVAL_MS

Los lanzadores leen AUTO_UPDATE_ENABLED antes de que arranque el servidor, así que un cambio se aplica a partir del próximo arranque y el registro no lo advierte.

Los ajustes de control de acceso y los secretos (BASIC_AUTH_USER, BASIC_AUTH_PASS, IP_ALLOWLIST, ADMIN_SECRET, CSRF_TRUSTED_ORIGINS) no necesitan reinicio.

Control de acceso

El control de acceso decide quién puede llegar a un servidor en ejecución. Para ver pasos y ejemplos, consulta Acceso remoto: inicio de sesión y lista de IP permitidas.

También puedes configurar el inicio de sesión sin .env: usa Settings → Advanced → Access (Configuración → Avanzado → Acceso) en un navegador que ya haya iniciado sesión, o el código de configuración de un solo uso del registro del servidor. El servidor imprime ese código solo mientras no hay inicio de sesión configurado y escucha más allá de loopback. El inicio de sesión se guarda en DATA_DIR/.remote-login.json. node scripts/reset-login.mjs (ejecutado en la carpeta de Marinara) lo elimina y cierra la sesión en todos los navegadores. Un inicio de sesión en .env tiene prioridad. Cambiar o quitar el inicio de sesión necesita la contraseña actual. Para los proxies de inicio de sesión, consulta Proxies de inicio de sesión (forward auth).

Términos usados abajo:

• Loopback: la computadora en la que se ejecuta el servidor, en 127.0.0.1 o localhost.
• Rango CIDR: una forma corta de escribir un bloque de direcciones IP, como 192.168.1.0/24.
• Basic Auth: un nombre de usuario y una contraseña que se envían con cada solicitud. Lo usan los scripts y los clientes de API, y los navegadores usan la página /login. Está codificado, no cifrado, así que usa HTTPS en un servidor público.

Sin inicio de sesión configurado, el servidor acepta solo fuentes de confianza: loopback, las direcciones de IP_ALLOWLIST, Tailscale y el tráfico del puente de Docker del mismo host. Todos los demás, incluida tu red doméstica, reciben 403 Forbidden. Para que otros dispositivos puedan conectarse siquiera, el servidor debe enlazarse a una dirección alcanzable: establece HOST=0.0.0.0.

Advertencia: un rango público amplio en IP_ALLOWLIST, como 0.0.0.0/0, puede dejar entrar a clientes de internet sin iniciar sesión. Incluye solo direcciones de confianza.

Almacenamiento

Genera una clave de cifrado y pégala en ENCRYPTION_KEY:

openssl rand -hex 32

Marinara guarda tus datos como archivos JSON simples, así que puedes copiar y leer las copias de seguridad. Para saber qué contiene cada carpeta, consulta Dónde se guardan tus datos.

Niveles de registro

LOG_LEVEL establece cuánto imprime el servidor. Oculta todo lo que esté por debajo del nivel que elijas.

En una terminal, el servidor imprime líneas legibles. En otros lugares, como los registros de Docker, un servidor de producción imprime líneas JSON. El lanzador de Termux pide líneas legibles. El registro del navegador es aparte y no lo controla LOG_LEVEL.

Tiempos de espera

Un tiempo de espera es lo máximo que el servidor aguarda por un trabajo lento. Abre Settings → Advanced → Request timeouts para cambiar en segundos los límites de texto, agentes, prompts de imagen de Game, imágenes, video, ComfyUI y embeddings. Los límites más altos ayudan a los backends locales lentos. No pueden anular un límite que imponga el servicio. Guardar necesita acceso de administración del servidor.

Esos ajustes se aplican a todos los perfiles y se guardan junto al .env activo como .env.timeouts.json (o <custom-env-path>.timeouts.json). Tienen prioridad sobre las variables correspondientes sin editar .env. Los cambios de texto, agentes, prompts de imagen de Game y embeddings se aplican a las nuevas solicitudes. Los cambios de medios y los paquetes de agentes instalados necesitan un reinicio. Para volver a las variables, elimina ese archivo y reinicia.

Los valores están en milisegundos a menos que el nombre diga lo contrario. Los valores no válidos, cero, negativos o fuera de rango de los tiempos de espera validados de chat, agentes y prompts de imagen de Game registran una advertencia y usan el valor predeterminado. Para saber más sobre los trabajos de video, consulta Video de escena.

APIs privilegiadas (ADMIN_SECRET)

Las acciones destructivas o de riesgo, como las copias de seguridad, borrar datos, aplicar actualizaciones e instalar temas, necesitan un secreto adicional además de las comprobaciones de acceso normales. Puedes crear uno en Settings → Advanced → Admin Access (Configuración → Avanzado → Acceso de administrador) en la propia computadora del servidor (consulta Admin Access), o establecer un valor largo y aleatorio en el servidor:

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

En la propia computadora del servidor, estas acciones suelen funcionar sin el secreto. Una solicitud que reenvía un proxy o un túnel en esa computadora cuenta como remota a menos que REQUIRE_AUTH_FOR_LOOPBACK_PROXY=false. Las solicitudes directas desde otro dispositivo necesitan el secreto. Pega el mismo valor en Settings → Advanced → Admin Access, y la app lo envía por ti. ADMIN_SECRET en .env tiene prioridad sobre un secreto creado en la app. Sin secreto de administrador, las acciones privilegiadas fallan desde todos los dispositivos excepto la propia computadora del servidor, y el error te indica que establezcas uno. Los agentes instalados funcionan desde cualquier dispositivo que haya entrado con el inicio de sesión; instalarlos, actualizarlos y quitarlos necesitan el secreto.

Aceptaciones de direcciones locales

De forma predeterminada, las solicitudes salientes a servicios de IA, servicios de imagen y webhooks rechazan las direcciones privadas o locales. Esto bloquea el SSRF (server-side request forgery, falsificación de solicitud del lado del servidor), en el que se engaña a una solicitud para que llegue a una dirección interna. Los servidores de modelos en loopback siguen funcionando. Activa solo el interruptor que necesites para un servicio autoalojado en otra máquina de la red privada.

Para conectar un modelo local o autoalojado, consulta Conectar un modelo local o autoalojado.

Interruptores de funciones

Los comportamientos opcionales del servidor, como reintentar las llamadas fallidas al proveedor o mantener estables las selecciones de grupos del lorebook, están en Settings → Advanced → Features (Configuración → Avanzado → Funciones). Todos están desactivados de forma predeterminada. Algunos tienen una variable que, cuando está definida, tiene prioridad sobre el interruptor. Consulta Interruptores de funciones.

Avisos de Marinara

Los avisos son advertencias breves de los mantenedores, como un problema de seguridad o un paso manual que necesita tu versión. Se muestran como un banner.

• Al arrancar y después cada hora, el servidor descarga un archivo pequeño, notices.json, de la rama notices del repositorio de Marinara Engine. Conserva solo los avisos que nombran tu versión. Tu navegador se los pide a tu propio servidor una vez al cargar la página y después cada hora.
• Si falla una descarga, el servidor conserva los avisos que ya tiene y el arranque no se retrasa.
• La petición no envía datos sobre ti, tus chats ni tus ajustes. Solo los mantenedores pueden cambiar la rama notices, y cada cambio se revisa.
• Un aviso es texto plano con un límite de tamaño. Los enlaces se conservan solo si apuntan a https://github.com/Pasta-Devs/. Un aviso no puede instalar, ejecutar ni cambiar nada.
• Solo tú ves los avisos: en la propia computadora del servidor, desde una dirección de IP_ALLOWLIST o después de iniciar sesión. Los demás visitantes reciben una lista vacía.

Para desactivar los avisos, establece MARINARA_NOTICES_ENABLED=false.

Advertencia: con los avisos desactivados, Marinara no puede avisarte de correcciones de seguridad ni de pasos necesarios. Sigue tú mismo las versiones en GitHub.

Las bifurcaciones pueden apuntar MARINARA_NOTICES_URL a su propio archivo.

Multijugador opcional

El multijugador está desactivado de forma predeterminada. Permite compartir una sala privada de Conversation, Roleplay o Game sin un límite fijo de participantes. Cada invitado usa su propia instalación de Marinara de confianza. Los invitados no necesitan cuenta de IA. El anfitrión proporciona las cuentas de IA y puede leer y conservar el contenido compartido. Mientras cualquiera de las dos condiciones de activación esté desactivada, Marinara no hace comprobaciones de sesiones, certificados ni pares en segundo plano.

1. Establece MULTIPLAYER_ENABLED=true en el .env de cada Marinara participante y reinícialo. Solo funciona el valor exacto true, y la recarga en caliente no lo aplica.
2. Abre Settings → Advanced → Multiplayer (Configuración → Avanzado → Multijugador), lee la advertencia y activa el ajuste. Esto no inicia un puerto de escucha ni se une a una sala.
3. Para alojar, usa Create shared session (Crear sesión compartida) o Play together (Jugar juntos) en el flujo del modo o de configuración. Revisa la configuración, tu nombre visible y el texto de persona que compartes. Un chat existente solo comparte sus selecciones de configuración, nunca su transcripción, notas ni recuerdos.
4. En el anfitrión, establece SSL_CERT y SSL_KEY para un certificado válido para el nombre de host de la sala y de confianza para los invitados. Elige una dirección HTTPS y un puerto de sala independientes, como https://room.example.org:7861. La acción de alojar abre ese puerto. Dirige solo el puerto de la sala a través de tu firewall o router. No expongas la API normal de Marinara. No se configura por ti ningún reenvío de puertos, retransmisión ni excepción de certificados.
5. Establece una contraseña de sala de al menos 12 caracteres, distinta de tus credenciales de administración. Envía la invitación que caduca y la contraseña por separado a personas de confianza. El invitado comprueba la huella del nombre de host, el nombre de la sala y el texto de persona, y luego solicita entrar. El anfitrión aprueba cada solicitud en Players (Jugadores) antes de que se envíe cualquier historial.

Límites y comportamiento:

• TLS comprueba la cadena del certificado y el nombre de host, y la huella del certificado de la invitación, antes de que se envíe una contraseña. Los certificados autofirmados no se aceptan en silencio. Un certificado renovado necesita una nueva invitación.
• Las invitaciones caducan a los 30 minutos. Las sesiones admitidas duran como máximo 12 horas. Reemplazar o revocar detiene las invitaciones sin usar. Kick (Expulsar) elimina a un invitado admitido.
• El anfitrión controla las respuestas automáticas o manuales, Pause (Pausar)/Resume (Reanudar) y Stop (Detener). El cupo predeterminado es de 100 turnos de generación coordinada por sesión de alojamiento. Un turno de grupo o la configuración de Game pueden hacer más de una llamada al modelo. Es un límite de turnos, no una estimación de precio.
• En Game, revisa el grupo antes de Start Game (Iniciar partida). Cada jugador requerido envía una acción o pasa, y el GM resuelve cuando todos están listos. Un jugador desconectado sigue siendo requerido hasta que vuelva o el anfitrión lo haga pasar o lo elimine. Las rondas pausadas o interrumpidas nunca repiten por sí solas una solicitud de pago ni efectos del mundo ya confirmados.
• Stop, Leave (Salir), desactivar el ajuste y reiniciar el servidor terminan la sesión activa. Un reinicio nunca aloja ni se une por sí solo.
• Las herramientas personalizadas y de paquetes y los comandos inseguros siguen sin estar disponibles en las salas. Los invitados nunca ejecutan un programador ni comandos locales a partir del texto recibido. Los horarios de Conversation usan el programador del anfitrión.
• Los nuevos jugadores y los cambios de persona se aplican en la siguiente ronda.
• Las salas solo transportan texto con límites de tamaño. No hay transferencia de archivos, medios, extensiones ni paquetes. El contenedor nativo de Android no puede unirse.

Advertencia: conéctate solo con personas de confianza y usa tu propio cliente de Marinara. Nunca instales un cliente, una extensión o un archivo proporcionados por el anfitrión. El anfitrión puede leer lo que compartes, y el contenido compartido puede ir a sus servicios de IA. Las conexiones directas revelan direcciones de red. No compartas contraseñas, API keys ni información personal. Sal de inmediato si algo parece ir mal.

Para las restricciones exactas y las plataformas probadas, consulta el registro de compatibilidad y verificación. Si tienes problemas, consulta Solución de problemas.

Agentes y extensiones

Instala los agentes propios opcionales en la app: Agents → Agent Organizer (Agentes → Organizador de agentes). Marinara elige el catálogo Pasta-Devs/Marinara-Agents que coincide con su versión mayor.

• Updates (Actualizaciones): Marinara pregunta antes de descargar una nueva versión de un paquete instalado. Not now (Ahora no) mantiene la versión actual y deja Update (Actualizar) en Agent Organizer. Una instalación nueva no tiene paquetes.
• Where packages live (Dónde viven los paquetes): DATA_DIR/capability-packages. Los volúmenes de Docker, las carpetas de datos personalizadas, las copias de seguridad y las actualizaciones normales los conservan. Esto se aplica al escritorio, Docker y Termux. iOS y otros navegadores usan los paquetes de su servidor anfitrión.
• Disk use (Uso del disco): Marinara conserva la versión actual y la anterior de cada paquete, y elimina las versiones más antiguas y las copias temporales de DATA_DIR/capability-runtime-snapshots. Los datos de los paquetes nunca se eliminan.
• Offline (Sin conexión): Los paquetes instalados siguen funcionando en su versión cuando GitHub es inalcanzable, se rechaza una actualización o falla la verificación.

Importaciones de agentes personalizados

Los archivos, las carpetas y los repositorios de agentes externos están bloqueados. Para permitirlos, activa Allow custom Agent imports (Permitir importaciones de agentes personalizados) en Settings → Advanced → Danger Zone (Configuración → Avanzado → Zona de peligro). Esto no necesita ninguna variable de entorno. Los controles de importación permanecen atenuados hasta que lo hagas.

Cada importación muestra primero las capacidades que solicita el agente. Los permisos necesitan aprobación explícita. No se importan las funciones incluidas ni las selecciones de herramientas, se sanea el CSS generado y se comprueban las acciones de resultado con las capacidades aprobadas. Desactivar la puerta detiene los agentes importados. Los agentes creados en Marinara y los paquetes oficiales no se ven afectados.

Repositorios de agentes personalizados

Los repositorios están desactivados de forma predeterminada porque sus prompts y herramientas no están verificados. Establece ENABLE_CUSTOM_AGENT_REPOS=true, activa Allow custom Agent imports y luego abre Agents → Agent Organizer → Custom Sources (Agentes → Organizador de agentes → Fuentes personalizadas) para previsualizar un repositorio público de GitHub. Añadir una fuente y aplicar cambios posteriores necesitan confirmación. La sincronización es manual, y Marinara nunca clona ni sondea repositorios en segundo plano. Solo se aceptan URLs de GitHub de la raíz de un repositorio.

Un repositorio publica agentes, conjuntos de reglas de Game Mode o ambos. En la raíz:

• agents.json es un array con el formato de agente descargable:

  [
    {
      "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 contiene un conjunto de reglas por archivo .json, hasta 32 archivos de 512 KB. Solo se leen los archivos que están directamente dentro. La vista previa muestra el nombre, la versión y la cobertura de cada conjunto de reglas. El texto para el Game Master de un conjunto de reglas se envía al modelo en cada partida que lo usa, así que instala solo de personas de confianza.

Los conjuntos de reglas importados llevan el nombre del propietario del repositorio, como alice/my-5e, así que nunca toman un nombre oficial. Se conserva cada versión, y una partida se juega con la versión exacta con la que empezó. Si llega la misma versión con un contenido diferente, Marinara conserva la instalada y te indica que pidas a quien lo creó que aumente el número de versión. Un archivo que Marinara no puede leer se lista con el motivo y se omite.

Al sincronizar, los valores remotos de prompt, ajustes y herramientas reemplazan los valores gestionados por el repositorio que muestra la vista previa. Tus elecciones de cuenta e imágenes siguen siendo locales. Si un agente desaparece del origen, se queda como un agente local normal y solo pierde su vínculo con el repositorio. Eliminar una fuente funciona igual, y sus conjuntos de reglas siguen instalados.

Los agentes personalizados también pueden activar Previous output (Salida anterior) en Context Sources para leer su última salida correcta. Con JSON context output (Salida de contexto en JSON), devuelve {"text":"main prompt content","agent-context":"private continuation context"}. Solo text va al prompt principal. Hide output as spoilers (Ocultar la salida como spoiler) mantiene contraídas las salidas guardadas. Las regeneraciones excluyen el turno reemplazado, y los mensajes eliminados o los swipes (respuestas alternativas) inactivos no pueden aportar contexto.

External Extensions

Las importaciones de extensiones de terceros necesitan dos aceptaciones. La variable de entorno es el permiso del operador del anfitrión. El interruptor de la Danger Zone es la aceptación del usuario.

1. Establece ENABLE_EXTERNAL_EXTENSIONS=true en .env.
2. Abre Settings → Advanced → Danger Zone, desplázate por debajo de los controles de eliminación de datos, lee la advertencia y activa Allow third-party extension imports (Permitir importaciones de extensiones de terceros).

Entonces aparece la sección External Extensions (Extensiones externas) en Settings → Addons. Cerrar cualquiera de las dos puertas desactiva los registros externos y detiene su código. Los registros almacenados manualmente, heredados, importados de un perfil y de origen desconocido cuentan como externos, así que soltar archivos en una carpeta no puede saltarse las puertas. Los borradores de Professor Mari no necesitan ninguna de las dos puertas. Empiezan desactivados y necesitan la aprobación de su hash de código exacto.

Las Sandboxed Browser Extensions (extensiones de navegador en entorno aislado) son la opción predeterminada. Algunos paquetes más antiguos muestran Full page access (Acceso completo a la página) porque necesitan la página de Marinara. Ese modo ejecuta el código aprobado en la página de Marinara, con acceso al contenido de la página, al almacenamiento del navegador, a las APIs de red y a tu sesión. Solo está disponible para las External Extensions con ambas puertas abiertas, y necesita una aceptación de advertencia aparte. Recarga la página después de desactivarlo.

Referencia completa de variables de entorno

Las tablas de arriba cubren el control de acceso, el almacenamiento, el registro, los tiempos de espera, las acciones privilegiadas y las aceptaciones de direcciones locales. Las demás variables están aquí.

Servidor y arranque

Schedule timezone usa de forma predeterminada la zona horaria de tu dispositivo. Puedes cambiarla durante la configuración de Conversation, en Conversation Chat Settings o en el editor de horario del personaje. Es un único ajuste global que comparten todos los chats de Conversation y que se sincroniza con otros clientes del mismo servidor.

Herramientas de medios y sprite

Proveedores de video de escena

Las cuentas de video se configuran en la app. Estos ajustes solo afinan los trabajos. Los valores están en milisegundos.

Lorebooks

Ambos están desactivados de forma predeterminada y se aplican en la siguiente generación tras un cambio en .env. Cuando LOREBOOK_STABLE_GROUP_WINNERS está definida, tiene prioridad sobre el interruptor Stable lorebook picks (Selecciones estables del lorebook) de Settings → Advanced → Features. Si no, decide el interruptor. Consulta Interruptores de funciones.

scripts/compact-lorebook-scans.mjs aplica la misma regla a los chats más antiguos. Detén primero el servidor. Es una simulación a menos que pases --apply, y hace una copia de seguridad de ambas tablas de mensajes antes de escribir.

Robustez

Todos están desactivados de forma predeterminada, lo que mantiene el comportamiento anterior. STORAGE_CACHE_WINDOWS_BOOT_ID, SHUTDOWN_WINDOWS_CONSOLE_SIGNALS y SHUTDOWN_FORCE_EXIT_ON_REPEAT necesitan un reinicio. Los demás se aplican tras un cambio en .env. Cuando PROVIDER_RETRY_TRANSIENT_ERRORS está definida, tiene prioridad sobre el interruptor Retry failed provider calls (Reintentar llamadas fallidas al proveedor) de Settings → Advanced → Features. Si no, decide el interruptor.

Integraciones y extras

Para el Built-in model, consulta Configuración del modelo integrado.

Proxy HTTP saliente

Algunas redes solo llegan a internet a través de un proxy HTTP, por ejemplo v2rayN sin el modo TUN. Marinara puede enviar a través de él las solicitudes a servicios de IA, servicios de imagen, servidores de embeddings y el catálogo de agentes. Establece estas variables en el entorno donde se inicia Marinara o en .env, y luego reinicia.

Guías relacionadas

• Interruptores de funciones
• Acceso remoto: inicio de sesión y lista de IP permitidas
• Dónde se guardan tus datos
• Conectarse a un proveedor de IA
• Video de escena
• Solución de problemas de Marinara Engine