Instalación y Configuración de Eveland

Eveland es una infraestructura de código abierto diseñada específicamente para el despliegue, enrutamiento y observabilidad de flotas de agentes basados en el protocolo Eve. A diferencia de las soluciones SaaS convencionales, Evelard ofrece soberanía total sobre los datos y la ejecución, permitiendo a las organizaciones gestionar múltiples agentes con aislamiento de seguridad industrial y escalabilidad dinámica.

Esta guía proporciona un recorrido técnico paso a paso para instalar Eveland en entornos Linux, configurando sus componentes críticos como el Agent Gateway, el Worker y sistemas de observabilidad integrados.

1. Requisitos Previos y Preparación del Entorno

Antes de iniciar la instalación, es fundamental que el servidor cumpla con los requisitos técnicos mínimos para garantizar la seguridad y el rendimiento del sistema:

Sistema Operativo: Distribución Linux (recomendado Ubuntu 22.04+ o Debian 12+) para asegurar compatibilidad con bubblewrap y cgroups.
Runtime de Node.js: Versión 24 o superior.
Gestor de Paquetes: pnpm 11 (requerido para la gestión del monorepo en entornos de desarrollo).
Base de Datos: PostgreSQL instalado y configurado para persistir estados, logs de sesión y configuraciones de agentes.
Dependencias de Sistema: Herramientas de red básicas y soporte para namespaces de usuario (necesario para el sandboxing real).

2. Métodos de Instalación

Eveland distingue claramente entre un entorno de desarrollo local y una implementación de producción robusta.

A. Despliegue en Producción (Recomendado)

Para entornos de producción, se utiliza el método nativo que configura unidades systemd. Este método es el único que habilita correctamente el sandboxing mediante bubblewrap y la gestión de recursos vía cgroup, garantizando que los agentes no tengan acceso a privilegios del sistema.

# Ejecutar el script oficial de instalación
curl -fsSL https://eveland.ai/install.sh | sudo bash

Nota: El script automatiza la creación de usuarios no privilegiados, la configuración de rutas y la generación de los archivos de unidad para systemd.

B. Desarrollo Local (Docker)

Si solo necesitas probar agentes localmente o realizar pruebas rápidas sin preocuparte por el aislamiento extremo del kernel:

# Utilizar la imagen oficial para desarrollo rápido
docker run -it --name eveland_dev [IMAGE_TAG]

Advertencia: El modo Docker no se recomienda para producción debido a que las capas de abstracción pueden complicar el aislamiento real en ciertos kernels específicos.

3. Configuración de Variables de Entorno

Tras la instalación, debes configurar las variables críticas en el archivo de configuración (gestionado por systemd o tu gestor de secretos). Estas variables definen el comportamiento del sistema:

EVELAND_ADMIN_PASSWORD: Define la contraseña para acceder al Dashboard administrativo.
BETTER_AUTH_SECRET: Clave necesaria para la gestión de identidad y autenticación OIDC. Debe ser una cadena aleatoria segura.
Observabilidad (OpenTelemetry & Langfuse): Configura los endpoints para rastrear el consumo de tokens, errores en tiempo real y pasos de razonamiento de los agentes.

4. Arquitectura de Seguridad: ¿Por qué no usar Docker en producción?

Una de las ventajas clave de Eveland es su enfoque Zero-Trust. El sistema separa el Agent Gateway (que maneja el tráfico público) del Worker (donde se ejecuta el código del agente).

El uso de bubblewrap en lugar de contenedores estándar permite que los Workers operen en sandboxes sin privilegios, limitando drásticamente el impacto si un agente intenta ejecutar código malicioso. Esta configuración es más difícil de replicar consistentemente en entornos Docker debido a las limitaciones de namespaces del kernel.

5. Verificación y Monitoreo

Una vez finalizada la instalación, verifica que los servicios estén activos y escuchando correctamente:

# Verificar el estado de las unidades systemd
systemctl status eveland

# Seguir los logs en tiempo real para detectar errores de inicio
journalctl -u eveland -f

Verifica que el Agent Gateway esté escuchando en el puerto configurado y que los Workers se activen bajo demanda (función scale-to-zero).

6. Mantenimiento, Actualizaciones y Rollback

Actualizaciones: Dado que Eveland está en estado pre-1.0, revisa siempre el CHANGELOG antes de actualizar para identificar cambios rotativos (breaking changes).
Backup: Realiza copias periódicas de la base de datos PostgreSQL. Es vital para recuperar estados de sesión y configuraciones personalizadas.
Rollback: En caso de fallo tras una actualización, restaura el último archivo de configuración válido y reinicia el servicio con systemctl restart eveland.

7. Errores Comunes y Soluciones

Problema	Causa Probable	Solución
Fallo en el Worker	Permisos de bubblewrap o cgroup insuficientes.	Verifica que el usuario del sistema tenga permisos para crear namespaces y que los límites de cgroup estén configurados.
Error de Autenticación	BETTER_AUTH_SECRET mal generado o ausente.	Regenera la clave usando un generador aleatorio y reinicia el servicio.
Puerto en uso	Conflicto con otro servicio (ej. Nginx).	Cambia el puerto del Gateway en las variables de entorno o usa un proxy inverso.

Preguntas Frecuentes (FAQ)

¿Eveland está relacionado con Vercel?: No, Eveland es una plataforma independiente que implementa el protocolo de agentes Eve. No tiene afiliación oficial con Vercel.
¿Por qué se recomienda systemd sobre Docker para producción?: Para garantizar un aislamiento real (Zero-Trust), Eveland utiliza bubblewrap sobre Linux nativo, lo cual es más robusto en términos de seguridad de kernel que las capas de abstracción estándar de Docker.
¿Qué es el protocolo Eve?: Es un estándar para la comunicación y ejecución de agentes IA, proporcionando una estructura común para flotas de agentes en entornos de producción.

Cómo instalar y configurar Eveland