Introducción
Documentación de Juvixbot
Guía técnica y operativa para instalar, configurar y proteger Juvixbot en tu equipo, gestionando proveedores comerciales y modelos locales con privacidad.
Juvixbot está en desarrollo y se ejecuta desde el código fuente en macOS. Las funciones marcadas «En desarrollo» pueden cambiar.
Requisitos del sistema
Juvixbot está diseñado y optimizado específicamente para la plataforma macOS:
- macOS 12 (Monterey) o superior. Totalmente compatible con procesadores Apple Silicon (M1, M2, M3, M4) y arquitecturas Intel de 64 bits.
- Node.js 18 o superior (recomendado Node 20 LTS o Node 22) con gestor de paquetes
npm. - Git instalado para clonar el repositorio de desarrollo.
- Xcode Command Line Tools (necesario para compilación nativa en macOS; ejecutable mediante
xcode-select --install). - Al menos una API de IA (OpenAI, Anthropic, Gemini, Groq, DeepSeek, etc.) o bien un servidor local en ejecución (Ollama o LM Studio).
Instalación paso a paso
Durante la actual fase de desarrollo (v0.2.0), Juvixbot se ejecuta directamente desde el código fuente para garantizar que inspecciones cada componente antes de otorgarle permisos:
1. Clonar el repositorio
Abre Terminal.app y clona el código fuente en tu carpeta de proyectos:
git clone https://github.com/usuario/juvixbot.git
cd juvixbot2. Instalar las dependencias
Descarga los módulos de Node y binarios de Electron:
npm installNota sobre Electron: Si durante la primera instalación en macOS recibes un mensaje indicando path.txt missing, ejecuta simplemente npx electron -v para que el binario de Electron termine de descomprimirse en tu sistema.
3. Iniciar la aplicación
Compila los recursos de interfaz y arranca el proceso principal de Electron:
npm startLa aplicación abrirá la ventana principal mostrando la pantalla de bienvenida con el modelo 3D y el selector de conversaciones.
Configuración inicial
Al abrir la aplicación por primera vez, te recomendamos seguir estos tres pasos básicos:
- Elige tu carpeta de trabajo predeterminada: En Ajustes → General, define la carpeta raíz donde sueles tener tus proyectos de código. El agente tomará esa ruta como espacio de trabajo por defecto.
- Personaliza tu identidad: En Ajustes → Cuenta, define tu apodo, nombre visible y tu rol profesional (por ejemplo, «Desarrollador Frontend» o «Ingeniero de Datos»). Esto permite que el modelo adapte sus explicaciones técnicas a tu nivel.
- Configura al menos un proveedor: Ve a Ajustes → Proveedores para vincular tus claves de API o detectar tus modelos locales.
Gestión de APIs y Proveedores
Juvixbot soporta 22 proveedores preconfigurados, permitiéndote utilizar tus propias cuentas y tarifas directas sin sobrecostes ni suscripciones intermediarias:
Proveedores comerciales compatibles
- OpenAI (
api.openai.com): GPT-4o, GPT-4o-mini, o1, o3-mini. Obtén tu clave enplatform.openai.com. - Anthropic (
api.anthropic.com): Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus. Gestión enconsole.anthropic.com. - Google Gemini (
generativelanguage.googleapis.com): Gemini 2.0 Flash, Gemini 1.5 Pro. Claves en Google AI Studio (aistudio.google.com). - DeepSeek (
api.deepseek.com): DeepSeek-V3, DeepSeek-R1 (razonamiento matemático y código a coste ultrabajo). - Groq (
api.groq.com): Inferencia ultrarrápida para Llama 3.3 70B, Mixtral y Whisper. - Mistral AI: Mistral Large, Codestral, Pixtral.
- OpenRouter (
openrouter.ai): Pasarela unificada para acceder a cientos de modelos abiertos y propietarios con una sola clave o mediante OAuth. - Otros proveedores compatibles con API OpenAI: xAI (Grok), Together AI, Fireworks, DeepInfra, Cerebras, Cohere, Novita, SiliconFlow y Cloudflare Workers AI.
Cómo conectar una clave de API
- Abre la ventana de Ajustes pulsando el icono de engranaje o con el atajo
Cmd + ,. - Selecciona la pestaña Proveedores.
- Localiza el proveedor que deseas activar (por ejemplo, OpenAI o Google Gemini).
- Pega tu clave secreta (con formato
sk-...o similar) en el campo correspondiente y pulsa Guardar. - Juvixbot validará la clave de inmediato mediante una consulta ligera a la lista de modelos. Si es correcta, el indicador cambiará a color verde con la etiqueta Conectado.
Modelos locales y privacidad
Si deseas trabajar sin conexión a Internet o procesar información confidencial sin enviarla a servidores externos, Juvixbot cuenta con soporte nativo para motores locales:
- Ollama: Descarga y ejecuta Ollama en tu Mac. Juvixbot detecta automáticamente el servicio en
http://127.0.0.1:11434y lista todos los modelos instalados (comollama3.3,qwen2.5-coder,deepseek-r1:8bomistral). - LM Studio: Inicia el servidor local de LM Studio en el puerto
1234. Juvixbot se conectará automáticamente mediante la interfaz compatible con OpenAI.
Los modelos locales no consumen cuota de red, no requieren claves de API y procesan toda la información exclusivamente en la GPU/Neural Engine de tu equipo.
Conmutación y Fallback automático por saldo
Uno de los problemas más frecuentes al trabajar con asistentes de IA es la interrupción de tareas cuando un proveedor agota su cuota de saldo (error HTTP 402) o alcanza el límite de velocidad por minuto (error HTTP 429).
Juvixbot incorpora un motor de conmutación inteligente:
- Si el modelo principal falla por motivos de saldo o disponibilidad antes de responder, Juvixbot conmuta de manera transparente a otro proveedor compatible que tengas conectado (por ejemplo, pasando de Claude 3.5 Sonnet a GPT-4o o Gemini 2.0 Flash).
- El contexto de la conversación, los archivos leídos y las herramientas ejecutadas se transfieren sin pérdida de estado.
- En la interfaz se muestra una notificación discreta informando del cambio de proveedor para que siempre sepas con qué modelo estás interactuando.
- Puedes personalizar el orden de prioridad o restringir el fallback únicamente a proveedores seleccionados en Ajustes → Proveedores → Enrutado.
Seguridad y Almacenamiento de Claves
La seguridad de tus credenciales y archivos es el pilar central de la arquitectura de Juvixbot:
- Cifrado con el Llavero de macOS: Las claves de API se cifran mediante
safeStoragede Electron, que utiliza directamente el Llavero del sistema operativo (Apple Keychain) con claves derivadas por hardware. Las credenciales se almacenan en el archivo protegidokeys.bindentro de tu directorio de usuario. - Aislamiento de la interfaz (Sandbox): La ventana visual donde interactúas se ejecuta con
contextIsolation: trueynodeIntegration: false. La interfaz web no tiene acceso al sistema de archivos ni puede leer tus claves de API; solo recibe del proceso principal un indicador booleano de si el proveedor está conectado o no. - Enmascaramiento de secretos: Antes de guardar un comando, paso o registro en el historial de la conversación, Juvixbot analiza el texto y enmascara automáticamente cadenas que coincidan con patrones de claves de API (
sk-..., tokens Bearer, contraseñas y certificados) para que nunca queden expuestas en los volcados. - Cero telemetría externa: Juvixbot no incluye analítica de uso, seguimiento de clics ni conexiones ocultas a servidores centrales. Las únicas conexiones de red salientes son las que tú autorizas hacia las APIs de los proveedores elegidos.
Permisos del agente y Matriz de Riesgos
Cuando un agente necesita realizar una acción en tu equipo, cada herramienta está catalogada con un nivel de riesgo estricto:
| Nivel | Operaciones | Comportamiento por defecto |
|---|---|---|
read | Listar carpetas (list_dir), leer código (read_file), buscar texto (search_text), consultar web (web_search). | Automático. El agente lee y analiza sin interrumpirte. |
write | Crear o modificar archivos del proyecto (write_file, edit_file), redactar notas. | Previa aprobación en modo manual; en modo automático se muestra el diff de cambios antes de aplicar. |
exec | Ejecutar comandos en la terminal de macOS (run_shell), como npm test o git status. | Control riguroso. Comandos comunes se ejecutan informando del resultado; comandos sensibles solicitan confirmación individual. |
desktop | Control de ratón, teclado, capturas de pantalla y activación de ventanas. | Autorización explícita. Requiere permisos de Accesibilidad de macOS y confirmación de acciones sensibles. |
Guardarraíles no saltables: Con independencia del modo de aprobación seleccionado, Juvixbot bloquea de forma incondicional comandos de destrucción masiva (como rm -rf /, borrado del directorio de inicio, escritura directa en bloques de disco o formateo) y exige confirmación obligatoria al interactuar con archivos de secretos como .env o claves SSH.
Contraseña de la aplicación y bloqueo local
Para proteger tus conversaciones y tus claves ante accesos físicos no deseados en tu Mac, puedes activar la protección con contraseña local:
- Ve a Ajustes → Cuenta.
- En la sección Seguridad y Bloqueo, pulsa Establecer contraseña.
- Introduce una contraseña segura de al menos 6 caracteres y confírmala.
- Activa la casilla «Solicitar contraseña al iniciar Juvixbot».
Una vez activada, cada vez que abras la aplicación se mostrará una pantalla de bloqueo que exigirá la contraseña antes de descifrar las sesiones o mostrar el panel de ajustes.
Memoria persistente y sincronización con Obsidian
Juvixbot aprende de tus preferencias y estilo de trabajo de forma adaptativa:
- Memoria adaptativa local: Guarda hechos, preferencias de frameworks (ej. «prefiero TypeScript estricto con interfaces») y decisiones arquitectónicas en
~/Library/Application Support/Juvixbot/memory. - Bóveda de Obsidian: En Ajustes → Obsidian, puedes seleccionar la carpeta local de tu bóveda. Juvixbot indexará de manera incremental tus notas en formato Markdown y recuperará fragmentos pertinentes mediante RAG local, citando la nota fuente cuando fundamente una respuesta.
Herramientas disponibles para el agente
El agente solo recibe las herramientas indispensables según el rol y la tarea en curso:
- Archivos y código:
list_dir(explorar directorios),read_file(lectura de fragmentos o archivos completos),search_text(búsqueda rápida por regex o texto),write_file(creación) yedit_file(edición quirúrgica por reemplazo exacto). - Terminal:
run_shell(ejecución de comandos con timeout, captura de código de salida y control de procesos). - Navegación web:
web_search(búsqueda de documentación actualizada) yweb_fetch/fetch_page(descarga y extracción del contenido de una URL). - Voz y audio:
speak_text(síntesis de voz con macOS say o ElevenLabs) y transcripción de voz nativa. - Subagentes:
delegate(permite al agente principal delegar una tarea de investigación a un subagente de solo lectura con contexto limpio e independiente).
Comandos de chat
Escribe / al comienzo de tu mensaje para desplegar la paleta de comandos interactivos:
| Comando | Propósito |
|---|---|
/compact | Resume los mensajes antiguos y compacta el contexto enviado a la API, ahorrando tokens sin perder el hilo. |
/tokens | Muestra el desglose detallado de tokens de entrada, salida, razonamiento y caché de la conversación activa. |
/cost | Calcula el coste monetario exacto acumulado en la sesión según las tarifas oficiales de tus proveedores. |
/clear | Limpia el contexto activo manteniendo las conversaciones guardadas en la barra lateral. |
/undo | Revierte el último cambio de código aplicado o la última acción ejecutada por el agente. |
/plan | Instruye al agente para generar un plan de acción detallado paso a paso sin escribir código todavía. |
/model | Abre el selector rápido para cambiar de modelo o ajustar el esfuerzo de razonamiento. |
Ahorro de tokens: resultados medidos
Juvixbot optimiza la ventana de contexto antes de cada llamada a la API eliminando redundancias y herramientas no utilizadas. Pruebas reales medidas en el proyecto (con gpt-4o-mini):
| Tipo de tarea | Tokens sin optimizar | Tokens con Juvixbot | Ahorro medido |
|---|---|---|---|
| Pregunta sencilla directa | 905 | 401 | −56 % |
| Conversación interactiva (6 turnos) | 7 742 | 2 374 | −69 % |
| Inspección de imagen (2400×1600) | 37 164 | 3 006 | −92 % |
| Bucle de agente autónomo | 4 609 | 2 778 | −40 % |
Solución de incidencias frecuentes
- Error 401 (Invalid API Key): Comprueba que no hayas copiado espacios adicionales al pegar la clave en Ajustes → Proveedores. Asegúrate de que la clave siga activa en la consola del proveedor.
- Error 429 (Rate Limit / Quota Exceeded): Has alcanzado el límite de peticiones por minuto o saldo de tu cuenta. Activa la opción de Fallback automático para que Juvixbot continúe con otro proveedor de reserva.
- El control del ordenador no mueve el ratón ni escribe: macOS exige permisos de seguridad explícitos. Abre Ajustes del Sistema → Privacidad y seguridad → Accesibilidad y asegúrate de que Juvixbot o tu terminal tengan el interruptor activado. Haz lo mismo en Grabación de pantalla.
- El micrófono no detecta sonido: Comprueba en Ajustes del Sistema → Privacidad y seguridad → Micrófono que la aplicación tenga autorización concedida.
Verificación y pruebas
Puedes verificar la integridad técnica de todo el proyecto en cualquier momento mediante los comandos oficiales:
node scripts/check-context.cjs # Comprueba consistencia documental y rutas
npm run typecheck # Verificación estricta de tipos TypeScript
npm test # Suite de pruebas automatizadas (521 tests)
npm run build # Compilación completa de producciónEliminar todos los datos y desinstalación limpia
Para desinstalar Juvixbot y borrar por completo cualquier rastro de tus sesiones, memorias y claves de tu Mac:
- Cierra la aplicación Juvixbot.
- Elimina la carpeta donde clonaste el repositorio.
- Abre la Terminal y elimina la carpeta de datos de usuario:
rm -rf ~/Library/Application\ Support/Juvixbot - Abre la aplicación Acceso a Llaveros (Keychain Access) de macOS, busca «Juvixbot Safe Storage» y elimínalo si deseas borrar la clave maestra del llavero.
- Si conectaste servicios externos de Google u OAuth, puedes revocar el acceso en el panel de permisos de tu cuenta de Google.
Consulta el historial detallado de cambios en la sección Cambios.