Instala y configura tus agentes de IA

Hay dos formas de usar oruka y esta guía es solo para una. En Pro y Managed la instancia la alojamos y operamos nosotros: no instalás Node, Docker, PostgreSQL, el sandbox ni OpenTelemetry, entrás a tu cuenta y listo. La base de datos es nuestra y es una sola para todas las cuentas — no elegís Postgres ni ves Configuración → Base de datos, porque no hay nada tuyo que configurar ahí. Lo único que cargás son las credenciales de tus propias integraciones: WhatsApp, Stripe, Shopify y demás. En Enterprise, en cambio, corrés todo en tu infraestructura bajo licencia perpetua: la base es tuya (contenedor local o alojada, como prefieras), las claves son tuyas y la administración también. Lo que sigue es esa segunda vía.

Node.js 24, Corepack con pnpm 10.33.2, y una clave de modelo con cupo disponible — del AI Gateway de Vercel, de OpenAI, de Anthropic o de Google Gemini. Docker solo hace falta si querés que PostgreSQL corra en tu propia máquina; apuntando la aplicación a una base alojada (Supabase, Neon, RDS) no se usa.

Un script instala todo lo que hace falta en macOS, Linux o Windows: Git, Docker, Node.js 24, pnpm, las dependencias del proyecto, PostgreSQL en Docker y las migraciones. Elegí tu plataforma:

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Manuekle/senka/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/Manuekle/senka/main/install.ps1 | iex

Después de la instalación, editá .env con tus claves de API y arrancá con pnpm dev. Cuando hay PostgreSQL disponible (WORKFLOW_POSTGRES_URL configurado), las cuentas y la facturación se guardan en la base de datos automáticamente. Si no hay PostgreSQL, la app usa archivos locales.

Instalá las dependencias y creá tu archivo de entorno a partir del ejemplo:

corepack enable
pnpm install --frozen-lockfile --strict-peer-dependencies
cp .env.example .env

Abrí ese .env antes de seguir: reemplazá las dos contraseñas de ejemplo y mantené POSTGRES_PASSWORD idéntica a la contraseña dentro de WORKFLOW_POSTGRES_URL. Ninguna clave de API va en el archivo: la del modelo y las de las integraciones se cargan después desde Configuración y Conexiones.

Levantá la base de datos, migrala y arrancá la aplicación:

pnpm db:up
pnpm db:migrate
pnpm dev

Abrí http://localhost:3000 y cargá desde ahí la clave del proveedor de IA y las de tus integraciones. Se guardan en ~/.oruka/credentials.json, se rotan y se borran desde la misma pantalla, y toman efecto sin reiniciar.

Esta pantalla dentro de la aplicación revisa en vivo si la máquina donde corre tiene todo lo que hace falta: versión de Node, si Docker está instalado y corriendo, el contenedor oruka-postgres, si WORKFLOW_POSTGRES_URL es alcanzable, si la base tiene sus tablas, la clave del modelo elegido, los embeddings, y el .env. Cada falla muestra el comando exacto que la resuelve.

La misma pantalla mueve configuración entre máquinas: podés importar un .env, un .txt o un JSON arrastrándolo o pegando el texto, y exportar todo lo guardado como .env agrupado o como JSON. La exportación incluye secretos en texto plano, y la pantalla lo avisa antes de que hagas clic.

PostgreSQL es la única base de datos que usa la aplicación, y hay dos formas de dársela. En tu propia máquina, docker-compose.yml la levanta en el puerto 5544 del host para no chocar con otro Postgres local, y POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB y POSTGRES_HOST_PORT configuran ese contenedor. Apuntando a una base alojada — Supabase, Neon, RDS — Docker no participa: alcanza con poner su cadena de conexión en WORKFLOW_POSTGRES_URL, y esos campos POSTGRES_* dejan de aplicar. Con Supabase, usá la cadena del pooler (Project settings → Database → Connection pooling) y conservá el ?sslmode=require. La aplicación deduce cuál de los dos casos es leyendo el host de la URL, así que Instalación (/setup) omite los chequeos de Docker y del contenedor cuando la base es remota. Todo esto se edita desde Configuración → Base de datos; una variable de entorno real siempre gana sobre un valor guardado ahí, y cambiar cualquiera requiere reiniciar el agente.

Por defecto la aplicación llama a los modelos a través del AI Gateway de Vercel con AI_GATEWAY_API_KEY. Como alternativa, OPENAI_API_KEY, ANTHROPIC_API_KEY o GOOGLE_GENERATIVE_AI_API_KEY llaman al proveedor directamente; AI_PROVIDER elige entre las cuatro rutas y, si lo dejás sin definir, se infiere de la clave que encuentre. Todas se pueden cargar y rotar en cualquier momento desde Configuración → Modelo de IA, y quedan guardadas en ~/.oruka/credentials.json. Los embeddings del Conocimiento (RAG) son la excepción: siempre corren por OpenAI o por el Gateway, así que una instalación que solo tenga clave de Anthropic o de Gemini necesita además una de esas dos. Además, cada conversación tiene su propio selector de modelo en el encabezado del chat.

El chat web funciona sin configurar nada. WhatsApp e Instagram necesitan una app de Meta, creada en developers.facebook.com: WhatsApp pide el token de acceso, el secreto de la app, el ID del número y un token de verificación; Instagram, que no depende de una página de Facebook, pide su propio token, su propio secreto —distinto del de la app—, el ID de cuenta y un token de verificación, y la cuenta tiene que ser profesional. El estado de cada canal (conectado o con datos faltantes) se ve en vivo en el panel, y las credenciales se cargan desde Configuración.

Conocimiento (/knowledge) indexa los documentos del negocio para que el agente responda con esa información en vez de inventar. Acepta PDF, TXT, MD, CSV, TSV, JSON, HTML, XML, YAML o LOG, hasta 20 MB por archivo — un PDF escaneado sin texto se rechaza con un aviso. El texto se parte en fragmentos de un tamaño fijo con superposición, se convierte en embeddings y queda guardado localmente; el agente busca sobre ese mismo índice con la herramienta search_knowledge, así que lo que ves en el buscador de la página es lo mismo que el agente puede encontrar. La misma página guarda fotos, videos y audios en carpetas: cada archivo lleva una descripción, y cuando un cliente pide ver algo el agente lo busca con find_media y lo manda con send_stored_media por WhatsApp o Instagram. Los límites los pone WhatsApp: 5 MB por foto y 16 MB por video.

Mis Agentes (/agents) crea agentes propios, con sus propias instrucciones y herramientas, con ayuda de IA para redactarlos. Automatizaciones (/automations) arma flujos que se disparan por un webhook de entrada, también con un asistente de IA que ayuda a escribir cada paso. Ambos quedan disponibles para elegir desde el resto de la aplicación una vez creados.

Conexiones (/connections) es el inventario de a qué tiene acceso esta instalación y quién lo autorizó. Arriba van las cuentas que se vinculan iniciando sesión: ahí el permiso se da en el dominio del proveedor y ninguna clave pasa por acá. Abajo van los proveedores cuya API no ofrece OAuth de usuario, con el motivo escrito en la tarjeta en vez de un botón Conectar que solo abriría un formulario: Stripe y Mercado Pago para los cobros, Shopify para consultar pedidos, Twilio, SMTP, ElevenLabs, Meta y las tres claves de modelo.

Registrar la app OAuth de un proveedor (su client ID y su secret) es tarea de la instalación, no de quien la usa: en Pro y Managed vienen por variable de entorno y nadie las ve, y en Enterprise se cargan una vez desde Configuración → Apps OAuth. Cada tarjeta abre el formulario de sus propias claves sin salir de la página. Cobros: el paso «Cobrar» de una automatización usa Stripe o Mercado Pago — Mercado Pago cubre ARS, BRL, CLP, COP, MXN, PEN y UYU, Stripe el resto. Shopify se conecta con el token de una app privada (permisos read_orders y read_customers) y habilita que el agente responda «¿dónde está mi pedido?» con los pedidos reales de la tienda.

Cada formulario tiene su propia URL pública y va guardando las respuestas paso a paso, así alguien que abandona en la pregunta dos ya queda en la bandeja con lo que contestó. La tarjeta Webhook de cada formulario agrega un endpoint tuyo al que se envía cada respuesta por POST en JSON, incompletas incluidas. Tiene que ser HTTPS y un host público. El campo response.id es estable entre pasos: conviene usarlo como clave para actualizar en lugar de acumular una fila por paso. Conexiones lista los formularios que tienen uno configurado, pero el webhook pertenece al formulario, no a la cuenta.

Anuncios (/ads) trae las campañas y los leads de tu cuenta de Meta Ads para verlos junto con el resto de las conversaciones, sin salir de la aplicación.

Configurando OTEL_EXPORTER_OTLP_ENDPOINT, la aplicación exporta trazas de Eve y del AI SDK a cualquier colector compatible con OTLP/HTTP. El repositorio trae Jaeger como opción local:

docker compose --profile observability up -d jaeger
# .env
OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"

El contenido completo de las entradas y salidas del modelo no se registra por defecto; OTEL_RECORD_INPUTS y OTEL_RECORD_OUTPUTS lo activan, y conviene revisar antes el colector, el control de acceso y cuánto tiempo retiene los datos.

La carpeta deploy/ provisiona con Ansible un droplet de DigitalOcean: los dos servicios de Node, PostgreSQL, Caddy para TLS, y opcionalmente Beszel para métricas del host y Jaeger para trazas. En producción, la aplicación exige las credenciales ROUTE_AUTH_BASIC_USER y ROUTE_AUTH_BASIC_PASSWORD — sin las dos, las rutas quedan cerradas. Antes de cada migración de esquema, Ansible guarda un backup de PostgreSQL en el propio servidor.