Guía práctica para instalar OpenJarvis en Windows desde cero: prerrequisitos, descarga de Ollama y resolución de los errores más frecuentes del proceso.

OpenJarvis es una plataforma de código abierto desarrollada en Stanford para construir agentes de inteligencia artificial que se ejecutan directamente en el hardware del usuario, sin depender de servidores externos. Desarrollado en los laboratorios Hazy Research y Scaling Intelligence Lab de Stanford SAIL, el proyecto parte de una premisa sencilla: la inteligencia artificial personal debería correr en el dispositivo personal del usuario. Un estudio previo del mismo equipo, llamado Intelligence Per Watt, encontró que los modelos de lenguaje locales pueden atender el 88.7% de las consultas de razonamiento de un solo turno a velocidades interactivas, y que la eficiencia de estos modelos mejoró 5.3 veces entre 2023 y 2025.

¿Qué es OpenJarvis y para qué sirve?

OpenJarvis organiza la inteligencia artificial local en cinco componentes que pueden intercambiarse de forma independiente: Intelligence (selección del modelo adecuado al hardware), Engine (el motor de inferencia que ejecuta el modelo), Agents (lógica de razonamiento de varios pasos), Tools y Memory (herramientas y memoria semántica), y Learning (mejora continua del comportamiento del agente a partir del historial de uso). La plataforma está licenciada bajo Apache 2.0 y recibe respaldo institucional de Google Cloud Platform, IBM Research, Stanford HAI y Lambda Labs.

Entre sus usos más concretos se encuentran: triaje de correos, resúmenes automáticos programados, análisis de documentos locales, asistencia de código integrable en editores como Visual Studio Code, y automatización de tareas recurrentes mediante agentes con horarios definidos, todo operando en el equipo del usuario sin enviar datos a servicios externos.

Requisitos de hardware para Windows

Antes de instalar cualquier componente, conviene verificar que el equipo cumple con los requisitos mínimos. Intentar ejecutar un modelo que supera la memoria disponible no genera un error claro; simplemente el sistema se vuelve muy lento o deja de responder.

¿Qué necesitas instalar antes de comenzar?

OpenJarvis depende de cinco herramientas externas. Ninguna es opcional si se planea usar la interfaz de navegador o la línea de comandos. Instalarlas en el orden indicado evita errores de rutas y variables de entorno.

Verificar si ya están instaladas

Antes de instalar cualquier cosa, abre PowerShell y ejecuta estos comandos para saber qué ya tienes disponible:

# PowerShell
git --version        # Esperado: git version 2.x.x o superior
python --version     # Esperado: Python 3.10.x o superior
node --version       # Esperado: v18.x.x o superior
npm --version        # Esperado: 9.x.x o superior
uv --version         # Esperado: uv 0.x.x
ollama --version     # Esperado: ollama version 0.x.x

Si algún comando devuelve “no se reconoce como comando interno o externo”, esa herramienta requiere instalación. Si el comando existe pero la versión es inferior a la mínima requerida, conviene actualizar antes de continuar.

Lista de prerrequisitos con enlaces de descarga

1. Git — necesario para clonar el repositorio.
   Descarga el instalador desde git-scm.com/download/win.
   Durante la instalación, acepta la opción de agregar Git al PATH del sistema.
2. Python 3.10 o superior — núcleo de la plataforma.
   Descarga desde python.org/downloads.
   Importante: en la primera pantalla del instalador, marca la casilla “Add Python to PATH” antes de continuar. Si se omite este paso, los comandos python y pip no funcionarán en PowerShell.
3. Node.js 18 o superior — requerido para la interfaz de navegador.
   Descarga la versión LTS desde nodejs.org/en/download.
   El instalador agrega Node.js y npm al PATH automáticamente.
4. uv — gestor de dependencias de Python utilizado por OpenJarvis.
   Una vez instalado Python, ejecuta en PowerShell:

   # PowerShell
   pip install uv

5. Ollama — el motor de inferencia recomendado. Se describe en detalle en la siguiente sección.

¿Cómo instalar Ollama en Windows?

Ollama es la herramienta que descarga y sirve los modelos de lenguaje de forma local. Sin Ollama funcionando en segundo plano, OpenJarvis no puede procesar ninguna consulta. Existen dos métodos de instalación en Windows.

Método 1: instalador gráfico (recomendado)

1. Descarga el instalador desde ollama.com/download/OllamaSetup.exe (aproximadamente 1.2 GB).
2. Ejecuta el archivo OllamaSetup.exe y sigue el asistente de instalación.
3. Al terminar, Ollama se inicia automáticamente como servicio en segundo plano y queda accesible en http://localhost:11434.
4. Verifica que responde abriendo PowerShell y ejecutando:

   # PowerShell
   curl http://localhost:11434
   # Respuesta esperada: Ollama is running

Método 2: instalación desde PowerShell

# PowerShell (como administrador)
irm https://ollama.com/install.ps1 | iex

Descargar un modelo base

Tras instalar Ollama, descarga al menos un modelo. El tiempo de descarga depende de la velocidad de conexión:

# PowerShell
# Modelo ligero (~400 MB, recomendado para equipos con 8 GB de RAM)
ollama pull qwen3:0.6b

# Modelo con mayor capacidad (~5 GB, requiere 16 GB de RAM disponible)
ollama pull qwen3:8b

# Verificar que el modelo quedó disponible
ollama list

Error: puerto ocupado al ejecutar ollama serve

Este es el error más frecuente en Windows tras instalar Ollama con el instalador gráfico:

Error: listen tcp 127.0.0.1:11434: bind: Only one usage of each socket address
(protocol/network address/port) is normally permitted.

Causa: El instalador gráfico de Ollama en Windows registra el servidor como un servicio del sistema que se inicia automáticamente. Cuando el usuario ejecuta ollama serve manualmente, el puerto 11434 ya está en uso por esa instancia. No es un error del sistema, sino una señal de que Ollama ya está funcionando correctamente.

Solución: No es necesario ejecutar ollama serve manualmente. Verifica que el servicio responde:

# PowerShell
curl http://localhost:11434
# Respuesta esperada: Ollama is running

Si la respuesta es Ollama is running, el servidor está listo. Si prefieres controlar el servicio manualmente, detén la instancia automática primero:

# Busca el ícono de Ollama en la bandeja del sistema
# (esquina inferior derecha de la barra de tareas)
# Clic derecho → "Quit Ollama"

# Luego inicia manualmente cuando lo necesites:
# PowerShell
ollama serve

Error: directorio de OpenJarvis no encontrado

Este error aparece al abrir la aplicación de escritorio de OpenJarvis sin tener el repositorio en la ubicación que la aplicación espera:

Could not find the OpenJarvis project directory.
Clone it with: git clone https://github.com/open-jarvis/OpenJarvis.git ~/OpenJarvis
then relaunch.

Causa: La aplicación de escritorio busca el repositorio en la carpeta de inicio del usuario (~/OpenJarvis), que en Windows equivale a C:\Users\TuUsuario\OpenJarvis. Si el repositorio fue clonado en otra ubicación, como C:\Users\vince\OpenJarvis clonando directamente desde C:\Users\vince\, la ruta puede coincidir, pero si se clonó en cualquier otro directorio la aplicación no lo encontrará.

Solución paso a paso:

1. Abre PowerShell y ve a tu directorio de inicio:

   # PowerShell
   cd ~
   # Equivale a: C:\Users\TuUsuario\

2. Verifica si el repositorio ya existe en la ubicación correcta:

   # PowerShell
   ls ~/OpenJarvis

3. Si no existe o está en otra ubicación, clónalo especificando la ruta de destino:

   # PowerShell
   git clone https://github.com/open-jarvis/OpenJarvis.git ~/OpenJarvis

4. Con el repositorio en su lugar, inicia el motor antes de abrir la aplicación:

   # PowerShell
   cd ~/OpenJarvis
   uv sync --extra server
   uv run jarvis serve

5. Con el servidor activo en http://localhost:8000, vuelve a abrir la aplicación de escritorio.

¿Por qué ./scripts/quickstart.sh no hace nada en Windows?

Los archivos con extensión .sh son instrucciones de Bash diseñadas para Linux y macOS. PowerShell no los ejecuta de forma nativa, por eso el comando no produce ninguna salida ni error visible.

Solución A — Usar WSL (Subsistema de Windows para Linux):

# PowerShell (como administrador), instalar WSL si no está disponible:
wsl --install

# Una vez dentro del entorno WSL:
cd ~/OpenJarvis
bash ./scripts/quickstart.sh

Solución B — Ejecutar cada paso manualmente en PowerShell (recomendada para mayor control):

# PowerShell — Paso 1: instalar dependencias de Python
cd ~/OpenJarvis
uv sync --extra server

# Paso 2: instalar dependencias del módulo visual
cd frontend
npm install
cd ..

# Paso 3: iniciar el servidor (mantener esta ventana abierta)
uv run jarvis serve

# Paso 4: abrir una NUEVA ventana de PowerShell e iniciar la interfaz visual
cd ~/OpenJarvis/frontend
npm run dev

La interfaz de chat estará disponible en http://localhost:5173 una vez que ambos procesos estén en ejecución.

Guía completa de instalación para Windows (flujo corregido)

Este es el flujo de instalación correcto para Windows, ejecutando cada paso en el orden indicado. Seguirlo de principio a fin evita los tres errores descritos anteriormente.

Fase 1: instalar prerrequisitos

1. Instala Git desde git-scm.com/download/win.
2. Instala Python 3.10 o superior desde python.org/downloads — marca “Add Python to PATH”.
3. Instala Node.js 18 o superior desde nodejs.org/en/download.
4. Instala uv:

   # PowerShell
   pip install uv

5. Instala Ollama descargando y ejecutando OllamaSetup.exe.

Fase 2: verificar que Ollama está activo y descargar un modelo

# PowerShell
# Verificar que Ollama responde (NO ejecutar "ollama serve" si usaste el instalador gráfico)
curl http://localhost:11434
# Respuesta esperada: Ollama is running

# Descargar un modelo base
ollama pull qwen3:0.6b

Fase 3: clonar OpenJarvis en la ubicación correcta

# PowerShell
cd ~
git clone https://github.com/open-jarvis/OpenJarvis.git ~/OpenJarvis
cd ~/OpenJarvis

Estructura del repositorio

Tras clonar el repositorio, esta es la estructura de carpetas y el propósito de cada una:

~/OpenJarvis/
├── frontend/        # Interfaz de navegador
├── scripts/         # Instrucciones de instalación para Linux y macOS
├── desktop/         # Aplicación nativa para escritorio
├── rust/            # Extensión opcional en Rust (uso avanzado)
├── tests/           # Pruebas automatizadas
└── pyproject.toml   # Configuración de dependencias de Python

Fase 4: instalar dependencias de OpenJarvis

# PowerShell
uv sync --extra server
cd frontend && npm install && cd ..

Fase 5: iniciar el servidor

# PowerShell — mantener esta ventana abierta
uv run jarvis serve

Fase 6: iniciar la interfaz visual

# PowerShell — abrir una NUEVA ventana
cd ~/OpenJarvis/frontend
npm run dev
# Abrir en el navegador: http://localhost:5173

Fase 7: verificar que todo funciona

# PowerShell — abrir una tercera ventana
cd ~/OpenJarvis

# Diagnóstico completo del entorno
uv run jarvis doctor

# Ver modelos disponibles
uv run jarvis model list

# Prueba de consulta directa
uv run jarvis ask "¿Cuál es la capital de Francia?"

# Verificar que el servidor responde
curl http://localhost:8000/v1/models

¿Qué motores de inferencia puedes usar con OpenJarvis?

OpenJarvis funciona con distintos motores de inferencia. La siguiente tabla resume las diferencias para elegir el adecuado según el hardware disponible:

Módulos opcionales

OpenJarvis mantiene una instalación base ligera. Las funcionalidades adicionales se activan según necesidad mediante el comando uv sync:

• Memoria vectorial FAISS: uv sync --extra memory-faiss
• Memoria ColBERTv2: uv sync --extra memory-colbert
• Memoria BM25: uv sync --extra memory-bm25
• Servidor compatible con la API de OpenAI: uv sync --extra server
• Herramientas de desarrollo y pruebas: uv sync --extra dev
• APIs en la nube (OpenAI, Anthropic): uv sync --extra inference-cloud
• API de Google Gemini: uv sync --extra inference-google

Es posible combinar varios módulos en un solo comando:

# PowerShell
uv sync --extra server --extra memory-faiss --extra inference-cloud

Errores adicionales frecuentes en Windows

• Error: 'jarvis' no se reconoce como comando
  El entorno de Python de uv no está activo en esa sesión de PowerShell.
  Solución: usa siempre el prefijo uv run jarvis en lugar de jarvis solo.
• Error: 'uv' no se reconoce como comando
uv no está instalado o no quedó en el PATH.
  Solución: ejecuta pip install uv y cierra y abre PowerShell de nuevo.
• Error: Python not found
  Python no se agregó al PATH durante la instalación.
  Solución: reinstala Python marcando “Add Python to PATH” o agrégalo manualmente en las variables de entorno del sistema.
• Error: Port 8000 already in use
  Otro proceso ocupa el puerto del servidor.
  Solución: uv run jarvis serve --port 8001
• La interfaz carga pero los mensajes no obtienen respuesta
  El servidor no está activo.
  Solución: verifica que uv run jarvis serve esté corriendo en otra ventana de PowerShell.
• Error: No engine detected
  Ollama no tiene modelos descargados o no está respondiendo.
  Solución: ejecuta ollama list para verificar. Si la lista está vacía, ejecuta ollama pull qwen3:0.6b.
• Windows Defender bloquea la conexión entre la interfaz y el servidor
  En algunos equipos, el cortafuegos de Windows bloquea las conexiones locales entre el módulo visual y el servidor de Python sin mostrar un error explícito.
  Solución: ve a Configuración → Privacidad y seguridad → Seguridad de Windows → Firewall y protección de red → Permitir una aplicación a través del firewall y agrega una excepción para el proceso Python y para ollama.exe.

¿Cómo actualizar OpenJarvis cuando salga una nueva versión?

# PowerShell
cd ~/OpenJarvis
git pull origin main
uv sync --extra server
cd frontend && npm install && cd ..
# Reiniciar el servidor y la interfaz visual

Uso desde la línea de comandos

Una vez que la instalación es exitosa, estos son los comandos más útiles del día a día:

• uv run jarvis ask "¿Cuál es la capital de Francia?" — consulta directa al modelo activo.
• uv run jarvis ask --agent orchestrator --tools calculator "¿Cuánto es 137 × 42?" — consulta con agente y herramienta de cálculo.
• uv run jarvis chat — sesión de conversación interactiva en la terminal.
• uv run jarvis serve --port 8000 — inicia el servidor compatible con la API de OpenAI.
• uv run jarvis model list — lista los modelos disponibles en el motor activo.
• uv run jarvis doctor — diagnóstico completo de configuración y conectividad.
• uv run jarvis init — detecta el hardware y genera la configuración óptima automáticamente.

Uso desde Python

Para integrar OpenJarvis en proyectos de Python, la clase Jarvis ofrece una interfaz directa:

from openjarvis import Jarvis

j = Jarvis()
print(j.ask("Explica el ordenamiento rápido en dos oraciones."))
j.close()

Para consultas que requieren agentes y herramientas:

result = j.ask_full(
    "¿Cuál es la raíz cuadrada de 144?",
    agent="orchestrator",
    tools=["calculator", "think"],
)
print(result["content"])       # "12"
print(result["tool_results"])  # herramientas invocadas
print(result["turns"])         # número de turnos del agente

Para control total sobre el proceso de inferencia, el constructor SystemBuilder permite configurar cada componente:

from openjarvis import SystemBuilder

system = (
    SystemBuilder()
    .engine("ollama")
    .model("qwen3:8b")
    .agent("orchestrator")
    .tools(["calculator", "web_search", "file_read"])
    .enable_telemetry()
    .enable_traces()
    .build()
)

result = system.ask("Resume el documento adjunto en cinco puntos clave.")
system.close()