Aixle Flow es una infraestructura crítica diseñada para cerrar el "Orchestration Gap". Cuando los equipos escalan el uso de agentes autónomos (como Claude Code o Cursor CLI), la visibilidad se pierde, los costos se vuelven opacos y las transiciones entre humanos y máquinas se fragmentan en hilos de Slack o copias manuales.

Esta guía detalla cómo desplegar Aixle Flow para centralizar el control, permitiendo que cada paso sea rastreable, cada fallo sea recuperable y cada costo esté contabilizado en un tablero Kanban nativo.

Nota: Antes de comenzar, consulta la ficha técnica oficial en Aixle Flow para conocer las capacidades completas del sistema y sus requisitos de infraestructura.

Arquitectura y Stack Tecnológico

Aixle Flow no es solo una interfaz; es un control plane robusto construido sobre tecnologías diseñadas para la alta disponibilidad:

Backend: Desarrollado en Ruby on Rails para una lógica de negocio sólida.
Persistencia: PostgreSQL para el estado del tablero y registros de auditoría.
Cache y Mensajería: Redis para la gestión de colas en tiempo real.
Motor de Flujo: Integración profunda con Temporal, garantizando que los flujos largos no se pierdan ante fallos de red o reinicios del servidor (durability).
Infraestructura: Despliegue mediante Docker y enrutamiento a través de Traefik.

Prerrequisitos

Para una instalación exitosa, tu entorno debe cumplir con los siguientes requisitos:

Docker y Docker Compose: Deben estar instalados y el daemon de Docker debe estar activo.
Conectividad: Acceso estable a internet para que los agentes se comuniquen con modelos (Anthropic, OpenAI, Google, etc.).
Credenciales API: Claves válidas para los servicios que planeas integrar (ej. Anthropic Key para Claude Code).
Espacio en Disco: Suficiente para las imágenes de Docker y el almacenamiento de datos de Temporal/PostgreSQL.

Pasos de Instalación

Sigue este procedimiento paso a paso para desplegar la infraestructura completa.

1. Clonar el Repositorio

Obtén el código fuente oficial y accede al directorio del proyecto:

git clone https://github.com/AixleHQ/flow.git
    cd flow

2. Configuración de Variables de Entorno

Crea el archivo de configuración local a partir del ejemplo proporcionado. Este paso es crítico para definir las credenciales y la configuración del sistema.

cp .env.example .env.development

Recomendación: Edita el archivo .env.development para incluir tus claves de API específicas antes de ejecutar los comandos de despliegue.

3. Preparación y Levantado del Sistema

Utiliza los scripts de automatización incluidos en el proyecto para configurar la base de datos, Redis y Temporal, y luego levanta todos los contenedores:

make setup && make up

El comando make setup prepara las bases de datos y configuraciones iniciales, mientras que make up inicia el stack completo (web, worker, db, redis, traefik, temporal).

Verificación del Sistema

Una vez finalizado el proceso de make up, verifica que los servicios estén operativos:

Interfaz Web: Accede a http://localhost:4000. Deberías ver el tablero principal de Aixle Flow.
Estado de Contenedores: Ejecuta docker ps para confirmar que los contenedores de Temporal, Redis y el servidor web estén en estado "running".
Conectividad de Agentes: Verifica en la consola que los agentes (Claude Code, etc.) puedan iniciar sus sesiones sin errores de autenticación.

Seguridad y Buenas Prácticas

Aislamiento de Agentes: Aixle Flow ejecuta cada agente en un contenedor Docker independiente. Esto evita que conflictos de dependencias entre herramientas (como diferentes versiones de Python o Node) afecten al sistema principal.
Gestión de Secretos: Nunca subas el archivo .env a repositorios públicos. Utiliza variables de entorno del sistema si despliegas en plataformas como Render o Railway.
Backups: Dado que utiliza PostgreSQL y Temporal, se recomienda realizar dumps periódicos de la base de datos para preservar el historial de flujos largos.
Control de Costos: Utiliza las funciones nativas de Aixle Flow para monitorear el consumo de tokens por sesión antes de escalar procesos masivos.

Errores Comunes y Soluciones

Problema	Causa Probable	Solución
Error en `make setup`	Falta de permisos en Docker o base de datos no accesible.	Asegúrate de que el usuario tenga permisos para ejecutar comandos de Docker y que los puertos no estén ocupados.
Conexión fallida a modelos (401/403)	Claves API incorrectas o sin saldo en `.env`.	Verifica las cuotas y la validez de tus llaves en el panel del proveedor (ej. Anthropic Console).
Lentitud extrema al inicio	Descarga inicial de imágenes pesadas de Docker.	El primer `make up` puede tardar entre 5 y 10 minutos dependiendo de tu conexión; espera a que los contenedores se estabilicen.

Preguntas Frecuentes (FAQ)

¿Es necesario tener Ruby instalado en mi máquina local?: Aunque el backend está desarrollado en Ruby on Rails, la mayoría de las operaciones se ejecutan dentro de los contenedores Docker. Solo es recomendable tener herramientas básicas si planeas modificar el código fuente directamente.
¿Cómo maneja fallos de red durante tareas largas?: Gracias a la integración con Temporal, el estado del flujo se guarda automáticamente. Si hay un corte de red o reinicio, el sistema reanuda la tarea exactamente donde quedó.

Fuentes: Repositorio Oficial | Documentación Oficial

Instalar y Configurar Aixle Flow