Instalar y ejecutar desde un binario precompilado#

Para cuando ya tienes — o quieres — solo el binario opendray, sin que ningún asistente de instalación toque tu máquina. Este es el camino para:

• npm install -g opendray / npx opendray — el paquete npm incluye el binario de release oficial de Go (ver README → npm / npx).
• Descargas de release — descarga opendray_*_<os>_<arch>.tar.gz desde la página de releases.
• Entornos con scripts / efímeros — runners de CI, imágenes doradas, gestión de configuración (Ansible, Nix, Docker), o cualquier host donde ya ejecutes tu propio Postgres y supervisor de procesos.

El binario es el gateway completo — la SPA de administración web está embebida, así que no hay runtime de Node, no hay servidor de archivos estáticos separado y nada que compilar. Lo que no hace es configurar nada por ti. Ese es el trato: tú aportas una base de datos PostgreSQL y una forma de mantener el proceso en marcha, y a cambio nada se instala, configura o registra sin que lo sepas.

¿Prefieres que todo lo haga por ti? En una máquina Linux / macOS recién instalada, el instalador de una sola línea provisiona Postgres, instala las AI-CLIs, escribe la configuración y registra un servicio en ~5–10 minutos. Consulta README → Instalador de una sola línea o el recorrido manual getting-started.md.

Esta guía te lleva de "binario en el PATH" a "gateway en marcha" en cinco pasos, y luego muestra cómo mantenerlo en ejecución como servicio.

Paso 1 — Obtener el binario#

Vía npm (cualquier SO con Node ≥ 18)#

El binario de plataforma correcto (opendray-{linux,darwin}-{x64,arm64}) se selecciona automáticamente vía optionalDependencies — no hay hook postinstall ni llamada de red durante la instalación. No uses --no-optional: omite el paquete de plataforma y deja al lanzador sin binario que ejecutar.

Vía archivo de release#

Verificar#

Plataformas soportadas: Linux (x64, arm64) y macOS (x64, arm64). Windows nativo no está empaquetado — usa WSL2 y sigue el camino de Linux.

Paso 2 — Proporcionar PostgreSQL 15+ con pgvector#

opendray almacena todo (sesiones, memoria, log de auditoría) en PostgreSQL, y su subsistema de memoria necesita la extensión pgvector. Versiones de servidor soportadas: 15, 16, 17.

Si ya ejecutas Postgres, crea una base de datos y un rol solo-CRUD, luego habilita la extensión una vez con un superusuario:

Una vez que la extensión existe, el rol solo-CRUD de opendray ejecuta migraciones sin ningún acceso adicional de superusuario. Nunca apuntes opendray a un rol superusuario en runtime — dale una cuenta con scope al proyecto y rota su contraseña fuera de banda.

Paso 3 — Configurar#

opendray lee su configuración desde un archivo TOML o puramente desde variables de entorno (12-factor) — las variables de entorno siempre tienen prioridad sobre el archivo. El único requisito estricto es la URL de la base de datos; todo lo demás tiene un valor por defecto.

Opción A — variables de entorno (recomendado para contenedores / hosts efímeros)#

Ejecuta opendray serve sin el flag -config y cargará todo desde el entorno.

Opción B — config.toml#

El mínimo a editar:

Consulta config.example.toml para el archivo completamente anotado (logging, detección de sesión inactiva, backups, vault, MCP). Pásalo con -config config.toml a los comandos de abajo. Mantén los secretos fuera del TOML en hosts compartidos — establece OPENDRAY_DATABASE_URL / OPENDRAY_ADMIN_PASSWORD vía entorno y deja el archivo sin secretos.

Paso 4 — Aplicar el esquema#

Idempotente — volver a ejecutarlo no tiene efecto una vez que el esquema está actualizado. Esto debe ejecutarse con éxito antes del primer serve.

Paso 5 — Ejecutarlo#

Esto se ejecuta en primer plano (Ctrl-C lo detiene). Deberías tener ahora:

Eso es un gateway completo y en marcha. Para cualquier cosa más allá de una prueba rápida, ejecútalo bajo un supervisor para que sobreviva a reinicios y se reinicie ante fallos — a continuación.

Ejecutarlo como servicio#

opendray serve es exactamente el comando de inicio que debería llamar la unidad de un servicio. opendray incluye unidades endurecidas y listas para usar; los pasos a continuación son los mismos que README → Despliegue de producción, que es la referencia autorizada (bootstrap completo, notas de sandboxing, reverse-proxy/TLS).

Linux — systemd#

El repositorio incluye una unidad endurecida en deploy/systemd/opendray.service (ejecuta migrate como ExecStartPre, secretos vía un EnvironmentFile, reinicio on-failure, sandboxing de syscall/filesystem).

¿Sin systemd? (LXC sin él, OpenRC, runit, s6, supervisord…) Apunta tu supervisor a opendray serve -config /etc/opendray/config.toml y ejecuta opendray migrate una vez como paso previo al inicio. Consulta README → Despliegue de producción §B.

macOS — launchd#

El repositorio incluye un LaunchDaemon en deploy/launchd/com.opendray.opendray.plist (arranca al inicio, se reinicia ante fallos, registra en /usr/local/var/log/opendray/).

Reiniciar: sudo launchctl kickstart -k system/com.opendray.opendray. Descargar: sudo launchctl bootout system/com.opendray.opendray.

Ambas unidades están documentadas en detalle — incluyendo el layout de secretos y por qué MemoryDenyWriteExecute está desactivado — en deploy/README.md.

Mantenerlo actualizado#

La forma de actualizar depende de cómo lo instalaste:

• Instalado vía npm — actualiza con tu gestor de paquetes. opendray update reemplazaría el binario dentro de node_modules a espaldas de npm y se sobreescribiría en la próxima instalación, así que no lo uses aquí.

  [object Promise]

• Descarga de release / instalación con asistente — el binario se autoactualiza en su sitio (descarga el último release, verifica su SHA-256, se intercambia a sí mismo atómicamente):

  [object Promise]

Solución de problemas#

the matching platform package "opendray-…" was not installed npm se ejecutó con --no-optional, o la instalación se interrumpió. Vuelve a ejecutar npm install -g opendray (sin --no-optional).

unsupported platform El paquete npm cubre Linux/macOS en x64/arm64 únicamente. En otros objetivos, compila desde el código fuente — consulta quickstart.md.

config: database.url is empty Ni OPENDRAY_DATABASE_URL ni [database].url están configurados. Establece uno (Paso 3).

connection refused en migrate/serve Postgres no está en ejecución o el DSN es incorrecto. Confirma que el servidor está activo y que el host/puerto/credenciales en tu DSN son correctos.

pgvector / extension "vector" is not available La extensión no está instalada en el servidor, o no se habilitó en la base de datos opendray. Repite el Paso 2 (instala el paquete del SO, luego CREATE EXTENSION vector como superusuario).

Puerto ya en uso Cambia OPENDRAY_LISTEN (o listen en config.toml) a un puerto libre.

Próximos pasos#

• README → Despliegue de producción — referencia completa de despliegue (systemd / launchd / supervisor propio, hardening, reverse proxy)
• docs/operator-guide.md — ops: topología de reverse-proxy/TLS, backups cifrados de DB, exportación/importación de datos
• docs/integration-guide.md — construye una integración externa contra la API REST + WebSocket
• docs/getting-started.md — la configuración guiada y todo-en-uno si prefieres no ensamblar las piezas tú mismo