Hive 🐝

Tu colmena de agentes IA. Local-first. Multi-canal. Open source. Construido desde Colombia para el mundo.

¿Qué es Hive?

Hive es un Gateway de IA Orquestado — un Enjambre de Agentes Especializados que trabajan juntos bajo la coordinación de un gateway central. A diferencia de un asistente personal único, Hive implementa una arquitectura de enjambre donde múltiples agentes especializados trabajan en equipo.

El problema que resolvemos: Necesitas un asistente de IA que funcione en múltiples canales (Telegram, Discord, WhatsApp), que pueda ejecutar tareas automáticamente, que respete tu privacidad con datos locales, y que sea extensible con herramientas propias.

Por dentro

51.937 líneas de TypeScript. Sin frameworks de agentes. Sin LangChain. Sin abstracciones intermedias. Todo construido desde cero sobre Bun + SQLite.

Language          files     blank   comment      code
─────────────────────────────────────────────────────
TypeScript          434      7671      2683     51937   ← motor, gateway, canales, UI
Markdown             45      2225         0      8233
JSON                 15         5         0       575
CSS                   1       141        29       450
YAML                  2        35        11       197
Shell                 2        14         5        61
Dockerfile            1        19        10        38
─────────────────────────────────────────────────────
TOTAL               504     10119      2741     61546

La imagen Docker pesa ~120 MB. El bundle npm pesa ~12 MB. El binario standalone ~50 MB. Todo el runtime cabe en una Raspberry Pi Zero 2W con 512 MB de RAM.

Instalación

Prerequisito — Bun

Hive requiere Bun como runtime para las opciones de binario y npm. Docker no lo requiere.

curl -fsSL https://bun.sh/install | bash
source ~/.bashrc   # o reinicia la terminal
bun --version      # verifica que quedó instalado

Elige la opción que mejor se adapte a tu caso:

	Docker	Binario	npm / bun
Requiere	Docker	Bun	Bun
Setup	1 comando	descarga + ejecuta	`bun install -g @johpaz/hive`
Actualizar	`docker compose pull`	descarga nueva versión	`bun install -g @johpaz/hive`
Ideal para	Raspberry Pi, VPS, laptop vieja, VM	uso personal, USB	desarrolladores
Abre navegador	automático (con GUI) / por IP (headless)	automático	automático
Tamaño	~120 MB imagen	~50 MB	~12 MB bundle

Opción 1 — Docker (Recomendada para servidores y VPS)

La forma más rápida. Sin instalar Node, Bun ni dependencias. Solo necesitas Docker.

Laptop, PC o VM con interfaz gráfica

Un solo comando que levanta todo y abre el navegador automáticamente:

curl -O https://raw.githubusercontent.com/johpaz/hive/master/docker-compose.yml
curl -O https://raw.githubusercontent.com/johpaz/hive/master/hive-docker.sh
chmod +x hive-docker.sh
./hive-docker.sh

El script levanta el contenedor, espera a que el gateway esté listo y abre el navegador directamente en /setup (primera vez) o en el dashboard (si ya está configurado).

Raspberry Pi, VPS o servidor headless

Sin interfaz gráfica, usa Docker Compose directamente:

curl -O https://raw.githubusercontent.com/johpaz/hive/master/docker-compose.yml
docker compose up -d

Luego accede desde cualquier equipo en la misma red usando la IP del servidor:

http://<ip-del-servidor>:18790

Para conocer la IP del servidor:

ip a | grep "inet " | grep -v 127.0.0.1

Raspberry Pi tip: si usas el mismo Pi para todo, http://raspberrypi.local:18790 suele funcionar sin necesitar la IP.

Con un solo comando (sin Compose):

docker run -d \
  -p 18790:18790 \
  -v hive-data:/root/.hive \
  --name hive \
  --restart unless-stopped \
  johpaz/hive:2.0.2

Variables de entorno disponibles:

Variable	Default	Descripción
`HIVE_HOST`	`0.0.0.0`	Interfaz de red donde escucha el gateway
`HIVE_PORT`	`18790`	Puerto del gateway
`HIVE_AUTH_TOKEN`	—	Token de autenticación (opcional)
`HIVE_LOG_LEVEL`	`info`	Nivel de logs (`debug`, `info`, `warn`, `error`)

Actualizar a la última versión:

docker compose pull        # descarga la imagen más reciente de Docker Hub
docker compose up -d       # reinicia el contenedor con la nueva imagen

Los datos (BD, config, logs) se persisten en el volumen hive-data — actualizar no borra tu configuración.

Ver logs en tiempo real:

docker compose logs -f hive

Acceso a archivos del sistema desde Docker

El docker-compose.yml monta automáticamente tu home completo dentro del contenedor — sin configuración adicional ni variables de entorno:

Sistema	Path del host	Path dentro del contenedor
Linux	`/home/tu_usuario`	`/host/home`
macOS	`/Users/tu_usuario`	`/host/home`
Windows	`C:\Users\tu_usuario`	`/host/home`

La variable ${HOME} la detecta el shell automáticamente al hacer docker compose up.

Configurar el workspace en la UI

Abre la UI: http://localhost:18790
Ve a Configuración del Agente (o crea tu agente si es la primera vez)
En el campo Workspace, configura el subdirectorio que quieres:
- /host/home — todo tu home
- /host/home/Documentos — solo carpeta Documentos
- /host/home/Proyectos — solo carpeta Proyectos

El path se guarda en la base de datos SQLite (agents.workspace). A partir de ese momento, todas las operaciones de filesystem del agente están restringidas a ese directorio por seguridad.

Ejemplo de uso:

Usuario: "Crea un archivo README.md en mi carpeta Proyectos"
Agente:  → Escribe en: /host/home/Proyectos/README.md
         → Que se traduce a: ~/Proyectos/README.md (en tu host)

Nota de seguridad: El agente solo puede acceder al path que configures como workspace. Si configuras /host/home/Documentos, no podrá leer /host/home/Proyectos.

Docker portable — USB o disco externo

Docker también puede viajar en una USB. La clave es exportar la imagen como archivo .tar y montar el volumen de datos desde la USB en vez de un volumen gestionado por Docker.

Paso 1 — Exportar la imagen a un archivo

En el equipo donde tienes conexión a internet:

# Descargar la imagen si no la tienes
docker pull johpaz/hive:2.0.2

# Exportar a archivo tar (cabe en cualquier USB de 512 MB+)
docker save johpaz/hive:2.0.2 -o /media/usb/hive-image.tar

Paso 2 — Crear la estructura en la USB

/usb/
├── hive-image.tar         ← imagen Docker exportada (~120 MB)
├── docker-compose.yml     ← archivo de configuración
└── datos/                 ← directorio de datos de Hive (se crea al primer arranque)
    └── hive.db

Crea el docker-compose.yml en la USB con el volumen apuntando a la USB:

services:
  hive:
    image: johpaz/hive:2.0.2
    ports:
      - "18790:18790"
    volumes:
      - ./datos:/root/.hive
    restart: unless-stopped

La clave es ./datos:/root/.hive — monta la carpeta datos/ relativa al docker-compose.yml, que está en la USB. Así los datos viajan con la USB, no quedan en el equipo.

Paso 3 — Cargar y ejecutar en cualquier equipo con Docker

# 1. Cargar la imagen desde el archivo (sin internet)
docker load -i /media/usb/hive-image.tar

# 2. Ir al directorio de la USB
cd /media/usb

# 3. Levantar
docker compose up -d

Abre http://localhost:18790 en el navegador. Si es la primera vez en ese equipo, muestra el wizard de setup. Si la USB ya tiene datos, carga tu agente directamente.

Detener y llevar la USB a otro equipo:

# Detener el contenedor
docker compose down

# En el otro equipo, volver al Paso 3

Nota para Windows: Docker Desktop usa rutas como D:\ para la USB. Ajusta el volumen en el docker-compose.yml a la letra de tu unidad:
volumes:
  - D:\datos:/root/.hive

Backup de los datos del contenedor:

# Copiar la BD desde la USB a tu máquina
cp /media/usb/datos/hive.db ~/backup-hive-$(date +%Y%m%d).db

# Restaurar
cp ~/backup-hive-20260312.db /media/usb/datos/hive.db

Actualizar la imagen en la USB:

# En un equipo con internet
docker pull johpaz/hive:latest
docker save johpaz/hive:latest -o /media/usb/hive-image.tar

# Actualizar el tag en docker-compose.yml
# Luego en cualquier equipo:
docker load -i /media/usb/hive-image.tar
docker compose up -d

Opción 2 — Binario standalone (Sin dependencias)

Descarga un ejecutable único para tu plataforma. No requiere Node, Bun ni Docker. Al ejecutarlo, el navegador se abre automáticamente en /setup (primera vez) o en el dashboard.

Dónde descargar

Desde la web — hiveagents.io La página detecta tu sistema operativo automáticamente y muestra el botón de descarga correcto. También puedes seleccionar otra plataforma desde el selector.

Desde GitHub Releases — github.com/johpaz/hive/releases/latest Descarga manual de cualquier plataforma o versión específica.

Plataforma	Archivo	Descarga directa
Linux x64	`hive-v2.0.2-linux-x64`	Descargar
Linux ARM64 (Raspberry Pi, etc.)	`hive-v2.0.2-linux-arm64`	Descargar
macOS Apple Silicon (M1/M2/M3/M4)	`hive-v2.0.2-macos-arm64`	Descargar
macOS Intel	`hive-v2.0.2-macos-x64`	Descargar
Windows x64	`hive-v2.0.2-windows-x64.exe`	Descargar

Los links anteriores siempre apuntan a la última versión publicada. Si necesitas una versión específica, visita la página de releases.

Linux x64 / ARM64

# 1. Descargar el binario (reemplaza "linux-x64" por "linux-arm64" si es ARM)
curl -L -o hive https://github.com/johpaz/hive/releases/latest/download/hive-v2.0.2-linux-x64

# 2. Dar permisos de ejecución
chmod +x hive

# 3. Descargar la UI web
curl -L https://github.com/johpaz/hive/releases/latest/download/ui-dist.tar.gz \
  | tar -xz --one-top-level=ui-dist

# 4. Colocar la UI donde Hive la espera
mkdir -p ~/.hive/ui
cp -r ui-dist/* ~/.hive/ui/

# 5. Ejecutar
./hive start

El gateway levanta en http://localhost:18790. El navegador se abre automáticamente.

Agregar al PATH (opcional) para ejecutar hive desde cualquier directorio:

sudo mv hive /usr/local/bin/hive
hive start

macOS — Apple Silicon (M1/M2/M3/M4)

# 1. Descargar
curl -L -o hive https://github.com/johpaz/hive/releases/latest/download/hive-v2.0.2-macos-arm64

# 2. Dar permisos de ejecución
chmod +x hive

# 3. Quitar la cuarentena de Gatekeeper (necesario en todos los binarios descargados)
xattr -d com.apple.quarantine hive

# 4. Descargar la UI
curl -L https://github.com/johpaz/hive/releases/latest/download/ui-dist.tar.gz \
  | tar -xz --one-top-level=ui-dist
mkdir -p ~/.hive/ui && cp -r ui-dist/* ~/.hive/ui/

# 5. Ejecutar
./hive start

¿Por qué el paso xattr? macOS bloquea binarios descargados de internet que no tienen firma de Apple. El comando xattr -d com.apple.quarantine elimina esa restricción. Si lo omites, verás el error: "hive no se puede abrir porque Apple no puede comprobar que no contiene software malicioso".

Alternativa: en Finder, haz clic derecho sobre el archivo → Abrir → Abrir de nuevo en el diálogo. Esto también lo desbloquea.

Error "there is no application set to open this document" El binario es un ejecutable de terminal — no se puede abrir con doble clic desde Finder. Siempre se ejecuta desde Terminal con ./hive start. Si aparece ese mensaje al hacer doble clic, ignóralo y usa Terminal.

Si después del xattr el error persiste, ve a Ajustes del Sistema → Privacidad y Seguridad y haz clic en "Abrir de todas formas".

Agregar al PATH:

sudo mv hive /usr/local/bin/hive
hive start

macOS — Intel

Igual que Apple Silicon pero descarga macos-x64:

curl -L -o hive https://github.com/johpaz/hive/releases/latest/download/hive-v2.0.2-macos-x64
chmod +x hive
xattr -d com.apple.quarantine hive
curl -L https://github.com/johpaz/hive/releases/latest/download/ui-dist.tar.gz \
  | tar -xz --one-top-level=ui-dist
mkdir -p ~/.hive/ui && cp -r ui-dist/* ~/.hive/ui/
./hive start

Windows x64

Paso 1 — Descargar el binario

Descarga hive-v2.0.2-windows-x64.exe desde GitHub o desde hiveagents.io.

Paso 2 — Windows SmartScreen

Al ejecutar por primera vez, Windows puede mostrar "Windows protegió tu PC". Es normal para binarios sin firma de código.

Haz clic en "Más información"
Luego en "Ejecutar de todas formas"

Paso 3 — Descargar la UI

Descarga ui-dist.tar.gz y extrae su contenido en:

C:\Users\TU_USUARIO\.hive\ui\

Puedes usar 7-Zip o WSL para extraer el .tar.gz. Con PowerShell 5+:

# Crear la carpeta de destino
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.hive\ui"

# Extraer (requiere PowerShell 5+ o Windows 11)
tar -xzf ui-dist.tar.gz -C "$env:USERPROFILE\.hive\ui"

Paso 4 — Ejecutar

.\hive-v2.0.2-windows-x64.exe start

El navegador se abre automáticamente en http://localhost:18790.

Agregar al PATH (opcional):

# Mover a una carpeta ya en el PATH, por ejemplo:
Move-Item .\hive-v2.0.2-windows-x64.exe C:\Windows\System32\hive.exe

# Luego ejecutar desde cualquier lugar:
hive start

¿Dónde se guardan los datos?

Todos los datos (base de datos, configuración, logs) se guardan en ~/.hive/:

~/.hive/                         # Windows: C:\Users\TU_USUARIO\.hive\
├── data/
│   └── hive.db        ← SQLite (agentes, conversaciones, config)
├── ui/                ← archivos de la interfaz web
├── logs/
│   └── gateway.log
└── gateway.pid

Variables de entorno disponibles:

Variable	Default	Descripción
`HIVE_HOME`	`~/.hive`	Directorio raíz de datos
`HIVE_PORT`	`18790`	Puerto del gateway
`HIVE_HOST`	`127.0.0.1`	Interfaz de red
`HIVE_UI_DIR`	`~/.hive/ui`	Ruta alternativa para la UI

Uso portable — USB o disco externo

El binario standalone es ideal para llevarlo en una USB. Tu agente viaja contigo con toda su memoria, historial y configuración.

Estructura recomendada en la USB:

/usb/
├── hive                  ← binario ejecutable
├── ui/                   ← archivos de la UI (extraídos de ui-dist.tar.gz)
└── datos/                ← directorio de datos (se crea automáticamente)
    ├── data/hive.db
    └── ...

Preparar la USB:

cp hive-v2.0.2-linux-x64 /media/usb/hive
chmod +x /media/usb/hive
cp -r ui-dist/* /media/usb/ui/

# (Opcional) llevar los datos existentes
cp -r ~/.hive/data /media/usb/datos/

Ejecutar desde la USB:

# Linux
HIVE_HOME=/media/usb/datos HIVE_UI_DIR=/media/usb/ui /media/usb/hive start

# macOS
HIVE_HOME=/Volumes/USB/datos HIVE_UI_DIR=/Volumes/USB/ui /Volumes/USB/hive start

Backup de datos:

cp ~/.hive/data/hive.db ~/backup-hive-$(date +%Y%m%d).db

Opción 3 — bun (Para desarrolladores)

Requiere Bun instalado — ver prerequisito al inicio de esta sección.

Instalación global:

bun install -g @johpaz/hive

Si instalas con npm install -g @johpaz/hive también funciona, pero igualmente necesitas Bun instalado — el CLI lo usa como runtime.

Iniciar:

hive start

El navegador se abre automáticamente en http://localhost:18790. Si es la primera vez, redirige a /setup para configurar tu agente.

Configurar desde terminal (sin browser):

hive onboard

Comandos útiles:

hive status          # estado del gateway
hive logs --follow   # logs en tiempo real
hive stop            # detener el gateway
hive doctor          # diagnóstico del sistema

Actualizar a la última versión:

bun install -g @johpaz/hive   # instala la versión más reciente
hive stop && hive start        # reinicia el gateway

Modo desarrollo (hot-reload + Vite, para contribuir al proyecto):

git clone https://github.com/johpaz/hive.git && cd hive
bun install
bun run dev

Migrar datos a otro equipo (portable):

El ejecutable de Hive queda instalado globalmente en el sistema, pero todos los datos viven en ~/.hive/ — agentes, conversaciones, configuración, API keys. Para llevarlos a otro equipo basta con copiar esa carpeta:

# En el equipo origen — comprimir los datos
tar -czf hive-datos.tar.gz -C ~ .hive

# Copiar a USB, disco externo o transferir por red
cp hive-datos.tar.gz /media/usb/

# En el equipo destino — instalar Hive y restaurar datos
bun install -g @johpaz/hive
tar -xzf /media/usb/hive-datos.tar.gz -C ~

# Arrancar — carga tu agente con toda su memoria
hive start

La carpeta .hive contiene la BD SQLite (data/hive.db), la UI web (ui/) y los logs. No contiene el binario de Hive — ese se reinstala con bun install -g.

Backup rápido solo de la BD:

cp ~/.hive/data/hive.db ~/backup-hive-$(date +%Y%m%d).db

Los Cuatro Pilares

Pilar	Descripción
Tools	Herramientas nativas: navegador, sistema de archivos, cron, canvas.
Skills	Habilidades incluidas: búsqueda web, shell, memoria, HTTP client, file manager.
MCP	Compatible con Model Context Protocol para extender funcionalidades.
Ética	Límites claros definidos en ETHICS.md — tu agente siempre sabe qué puede y qué no puede hacer.

Arquitectura técnica

Hive usa un Native Agent Loop propio — sin dependencias de LangGraph ni LangChain. Todo corre sobre Bun + SQLite con cero abstracciones intermedias.

Loop principal

mensaje entrante
  → Context Compiler (compileContext)
      → callLLM()
          → [executeTool() → callLLM()]*
              → respuesta al usuario

FASE 3 — Context Compiler

El Context Compiler es el componente central del motor. Se ejecuta antes de cada llamada al modelo y ensambla una "vista mínima" del contexto consultando SQLite directamente. Implementa cuatro estrategias de Context Engineering:

3.1 — Selección de historial (SELECCIONAR)

Conversaciones cortas (< 20 mensajes): pasa todos los mensajes
Conversaciones largas: usa el resumen de la tabla summaries + los últimos N mensajes recientes
Nunca pasa la conversación cruda completa a modelos con ventana chica

3.2 — Scratchpad (ESCRIBIR)

Carga las notas persistentes del thread actual desde la tabla scratchpad
Las inyecta en el system prompt como "Información conocida sobre esta conversación"
El agente puede escribir al scratchpad usando la tool save_note(key, value)

3.3 — Playbook del ACE (SELECCIONAR)

Busca con FTS5 en la tabla playbook usando keywords del mensaje del usuario
Inyecta máximo 5 reglas relevantes (active=1, helpful_count > harmful_count)
Las reglas son aprendidas automáticamente por el Curator del ACE

3.4 — Selección de tools en tres niveles (SELECCIONAR)

Nivel	Operación
1 — Catálogo	`collectNativeTools()` + tools de MCP activos
2 — Agente	`filterToolsByAgent()` — filtra por `tools_json` del agente. `NULL` = todas permitidas
3 — Turno	`selectToolLoadout()` — ALWAYS_INCLUDE + scoring por keywords del mensaje (máx. 20)

El límite de 20 tools por turno es crítico para modelos locales con recursos limitados. Las tools del ALWAYS_INCLUDE siempre están disponibles sin consumir slots opcionales: cron_add/list/remove/edit, project_create/task_create/task_update, read/write/edit, save_note, notify, report_progress, create_agent.

3.5 — Ética (capa constitucional)

Carga todas las reglas de la tabla ethics — sin filtrar, sin comprimir
Siempre es el primer bloque del system prompt, en toda llamada al modelo

Orden de ensamblaje del contexto:

[system prompt]
  1. Reglas de ética (completas, siempre)
  2. Identidad del agente (agents.system_prompt + description)
  3. Hive Capabilities Manifest (hive_capabilities table)
  4. Perfil del usuario (users table)
  5. Reglas del playbook relevantes (FTS5, máx. 5)
  6. Notas del scratchpad (filtradas por thread_id)
  7. Entorno (agent_id, thread_id, fecha/hora local)

[messages]
  8. Resumen del historial (si la conversación es larga)
  9. Mensajes recientes (últimos N)

[tools]
  10. Tools filtradas en tres niveles

FASE 4 — Proyectos, Tareas y Workers

El Coordinador puede descomponer problemas complejos en proyectos con tareas paralelas ejecutadas por workers autónomos.

4.1 — Decisión simple vs proyecto

El modelo decide en su system prompt:

Tarea simple → el Coordinador la resuelve directamente o despacha a un worker existente
Tarea compleja → crea un proyecto con subtareas y dependencias

4.2 — Creación de proyecto y asignación de workers

project_create — registra el objetivo del proyecto
task_create — crea cada subtarea con dependencias
find_agent — busca por FTS5 sobre name+description del agente vs la tarea
- Si existe un worker compatible → assign_task
- Si no → create_agent con system prompt y tools necesarios, luego assign_task

4.3 — Ejecución respetando dependencias

Tareas sin dependencias (o con dependencias ya completed) se ejecutan primero
Tareas independientes entre sí corren en paralelo (Promise.all)
Si una tarea falla: el Coordinador puede reintentar, reasignar a otro agente, o marcar el proyecto como failed

4.4 — Contexto aislado por worker (AISLAR)

Cada worker recibe solo lo necesario para su tarea:

Reglas de ética + su system prompt propio
Descripción de la tarea asignada
Resultados de las tareas de las que depende

El worker no recibe la conversación completa del usuario. Esto mantiene el contexto mínimo y evita contaminación entre agentes.

FASE 5 — ACE (Adaptive Context Engine)

El ACE convierte a Hive en un sistema que aprende automáticamente de sus propias ejecuciones.

5.1 — Tracer (Generator)

Después de cada ejecución se guarda automáticamente en la tabla traces:

Qué agente, qué tool, qué recibió, qué produjo
Si fue exitoso, cuánto tardó, cuántos tokens consumió

Pasivo — no agrega latencia al usuario.

5.2 — Reflector (análisis periódico)

Se ejecuta en segundo plano, nunca en el flujo del usuario:

Trigger: cada 20 trazas nuevas, o por cron periódico
Le pide al modelo que analice las trazas: patrones de éxito, fallos repetidos, oportunidades de mejora
Guarda los insights en la tabla reflections (incluyendo ethics_violation con prioridad máxima)

5.3 — Curator (playbook + poda de agentes)

Transforma insights en reglas operativas:

Si ya existe una regla similar → incrementa helpful_count o harmful_count
Si es nueva → la inserta con confidence proporcional a cuántas trazas la respaldan
Si harmful_count > helpful_count → marca la regla como active=0
Si hay reglas duplicadas o contradictorias → fusiona o poda

Poda de agentes:

Workers sin actividad por más de 14 días → status='archived'
Workers con tasa de fallo alta → archived + regla en playbook explicando por qué fallaba
Workers duplicados (skills similares) → archiva el menos exitoso

Ciclo completo del ACE:

Agentes ejecutan tareas
  → trazas en SQLite
      → Reflector analiza periódicamente
          → Curator actualiza playbook + poda agentes
              → Context Compiler inyecta reglas
                  → Agentes ejecutan mejor la próxima vez

FASE 6 — Compaction (compresión de historial)

Mantiene el contexto dentro del presupuesto de tokens del modelo.

Compresión de conversación (COMPRIMIR)

Trigger: cuando el token count acumulado del thread supera el 60% de la ventana del modelo
Toma todos los mensajes excepto los últimos 5
El modelo los resume preservando: datos del usuario, decisiones tomadas, resultados de tools, contexto para continuar
El resumen se guarda en la tabla summaries; los mensajes originales permanecen como historial

Tool result clearing

Resultados de tools con más de N turnos de antigüedad → reemplazados por un resumen corto
Reduce tokens sin perder el registro de que la tool se ejecutó

Providers LLM soportados

Hive llama directamente a los SDKs oficiales de cada provider:

Provider	SDK	Modelos ejemplo
Google Gemini	`@google/genai`	gemini-2.5-flash, gemini-2.0-flash
Anthropic	`@anthropic-ai/sdk`	claude-sonnet-4-6, claude-opus-4-6
OpenAI	`openai`	gpt-4o, gpt-4.1
Groq	`openai` (compat)	llama-3.3-70b, mixtral-8x7b
Mistral AI	`openai` (compat)	mistral-large, codestral
DeepSeek	`openai` (compat)	deepseek-chat, deepseek-reasoner
Kimi (Moonshot)	`openai` (compat)	moonshot-v1-8k, moonshot-v1-128k
Ollama	`openai` (compat)	llama3, qwen2.5, etc.
OpenRouter	`openai` (compat)	cualquier modelo de la plataforma

Onboarding → System Prompt

Al completar el onboarding, el campo agents.system_prompt se genera automáticamente con el nombre, descripción y tono del agente. El tono puede ser: friendly, professional, direct o casual.

Browser Automation con Lightpanda

Hive incluye 7 tools de browser automation para navegar, extraer datos, interactuar y automatizar sitios web con JavaScript rendering.

¿Por qué Lightpanda?

Lightpanda es un browser headless diseñado para ser 9x más liviano en RAM y 11x más rápido que Chrome. Es crítico para el principio local-first de Hive y para correr en hardware de bajo consumo como el NanoPi Neo3 Plus.

Principio fundamental: Lightpanda corre como proceso externo independiente. Hive no embebe ni compila Lightpanda — lo invoca via WebSocket CDP exactamente igual que Puppeteer se conecta a Chrome. Esto mantiene a Lightpanda como dependencia opcional de runtime, no como código derivado.

Tools disponibles

Tool	Descripción
`browser_navigate`	Navegar a URL y obtener contenido renderizado (soporta JS)
`browser_screenshot`	Capturar screenshot de la página (base64 PNG)
`browser_click`	Hacer click en elemento (CSS selector)
`browser_type`	Escribir texto en campos de formulario
`browser_extract`	Extraer datos con selectores CSS o XPath
`browser_script`	Ejecutar JavaScript arbitrario en el contexto de la página
`browser_wait`	Esperar por elemento o condición antes de continuar

Todas las tools de browser están activadas por defecto. Si Lightpanda no está disponible, las tools fallan gracefully sin afectar el resto de Hive.

Instalación de Lightpanda

Docker (Recomendado)

El docker-compose.yml de Hive incluye Lightpanda como servicio opcional comentado. Para activar:

# 1. Descomenta el servicio lightpanda en docker-compose.yml
lightpanda:
  image: lightpanda/browser:nightly
  ports:
    - "9222:9222"

# 2. Descomenta BROWSER_CDP_URL en el servicio hive
hive:
  environment:
    BROWSER_CDP_URL: ws://lightpanda:9222

docker compose up -d

Linux (binario nativo)

# x86_64
curl -L https://github.com/lightpanda-org/lightpanda/releases/latest/download/lightpanda-linux-amd64 \
  -o /usr/local/bin/lightpanda
chmod +x /usr/local/bin/lightpanda

# ARM64 (Raspberry Pi, NanoPi)
curl -L https://github.com/lightpanda-org/lightpanda/releases/latest/download/lightpanda-linux-arm64 \
  -o /usr/local/bin/lightpanda
chmod +x /usr/local/bin/lightpanda

macOS

# Apple Silicon (M1/M2/M3/M4)
curl -L https://github.com/lightpanda-org/lightpanda/releases/latest/download/lightpanda-darwin-arm64 \
  -o /usr/local/bin/lightpanda
chmod +x /usr/local/bin/lightpanda

# Intel
curl -L https://github.com/lightpanda-org/lightpanda/releases/latest/download/lightpanda-darwin-amd64 \
  -o /usr/local/bin/lightpanda
chmod +x /usr/local/bin/lightpanda

Iniciar Lightpanda como servicio

Systemd (Linux)

Crea /etc/systemd/system/lightpanda.service:

[Unit]
Description=Lightpanda Browser
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/lightpanda --port=9222
Restart=always
User=hive

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable lightpanda
sudo systemctl start lightpanda

Configuración

No requiere configuración. Las browser tools están activadas por defecto. Al arrancar, Hive intenta conectar automáticamente a Lightpanda en ws://127.0.0.1:9222.

✅ Si Lightpanda está disponible: Las 7 browser tools funcionan normalmente
⚠️ Si Lightpanda no está corriendo: Las tools fallan gracefully sin afectar el resto de Hive

Opcional: Si necesitas cambiar el puerto o URL, usa variables de entorno (solo usuarios avanzados):

Detección Automática

Al arrancar, Hive:

Intenta conectar a ws://127.0.0.1:9222 automáticamente
Si responde: las 7 browser tools están operativas
Si no responde: las tools fallan gracefully (sin crashear)

No requiere configuración del usuario.

Ejemplo de uso

// Navegar a una página con JavaScript rendering
const result = await browser_navigate({
  url: "https://example.com",
  waitFor: ".content-loaded",
  timeout: 30000,
});

// Extraer datos con selector CSS
const links = await browser_extract({
  url: "https://example.com",
  selector: "a[href]",
  attribute: "href",
  all: true,
});

// Tomar screenshot
const screenshot = await browser_screenshot({
  url: "https://example.com",
  fullPage: true,
});

// Ejecutar JavaScript
const data = await browser_script({
  script: `document.querySelector('.price').textContent`,
});

Recursos

Seguridad

Tema	Resumen
Autenticación	Define `HIVE_AUTH_TOKEN` siempre en producción. Sin él, cualquiera que alcance el puerto puede usar el dashboard.
Red	En VPS o servidores, pon Hive detrás de un reverse proxy con HTTPS y abre solo el puerto `18790`.
Container	El proceso corre como `root` dentro del contenedor (sin `--privileged`). Migración a usuario no-root pendiente en versiones futuras.
Datos	Todo se almacena en el volumen `hive-data` / `~/.hive/`. No se envía telemetría a servidores externos. Las API keys se guardan cifradas.

Consulta SECURITY.md para instrucciones detalladas de configuración, backup y hardening.

Desarrollo

# Clonar el repo
git clone https://github.com/johpaz/hive.git
cd hive

# Instalar dependencias
bun install

# Modo desarrollo
bun run dev

Contribuir

¿Quieres agregar una nueva funcionalidad? Consulta CONTRIBUTING.md para saber exactamente dónde hacer tu cambio.

Tipo de cambio	Ubicación
Canal nuevo	`packages/core/src/channels/` + registrar en `manager.ts`
Tool nativa	`packages/core/src/tools/` + registrar en `native-tools.ts`
Skill nueva	`packages/skills/src/`
MCP nuevo	`packages/core/src/mcp/`
Capability en el manifest	tabla `hive_capabilities` vía `seed.ts`
Mejora al CLI	`packages/cli/src/commands/`

Todo en un PR. Una revisión. Un merge.

Links

🌐 hiveagents.io
💬 Discord
📱 Telegram

Name		Name	Last commit message	Last commit date
Latest commit History 68 Commits
.github/workflows		.github/workflows
packages		packages
public		public
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
README.md		README.md
SECURITY.md		SECURITY.md
build.sh		build.sh
bun.lock		bun.lock
bunfig.toml		bunfig.toml
docker-compose.local.yml		docker-compose.local.yml
docker-compose.yml		docker-compose.yml
hive-docker.sh		hive-docker.sh
package.json		package.json
start.sh		start.sh
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Hive 🐝

¿Qué es Hive?

Por dentro

Instalación

Prerequisito — Bun

Opción 1 — Docker (Recomendada para servidores y VPS)

Laptop, PC o VM con interfaz gráfica

Raspberry Pi, VPS o servidor headless

Acceso a archivos del sistema desde Docker

Docker portable — USB o disco externo

Opción 2 — Binario standalone (Sin dependencias)

Dónde descargar

Linux x64 / ARM64

macOS — Apple Silicon (M1/M2/M3/M4)

macOS — Intel

Windows x64

¿Dónde se guardan los datos?

Uso portable — USB o disco externo

Opción 3 — bun (Para desarrolladores)

Los Cuatro Pilares

Arquitectura técnica

Loop principal

FASE 3 — Context Compiler

FASE 4 — Proyectos, Tareas y Workers

FASE 5 — ACE (Adaptive Context Engine)

FASE 6 — Compaction (compresión de historial)

Providers LLM soportados

Onboarding → System Prompt

Browser Automation con Lightpanda

¿Por qué Lightpanda?

Tools disponibles

Instalación de Lightpanda

Docker (Recomendado)

Linux (binario nativo)

macOS

Iniciar Lightpanda como servicio

Systemd (Linux)

Configuración

Detección Automática

Ejemplo de uso

Recursos

Seguridad

Desarrollo

Contribuir

Links

Licencia

About

Topics

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages