Skip to main content

Instalacion self-hosted

Esta guia te lleva de cero a una instancia de Almirant corriendo en tu maquina o servidor.

Tiempo estimado: 15-25 minutos (la mayor parte es build de imagenes Docker la primera vez).

Requisitos​

  • Docker 24+ y Docker Compose v2 instalados y corriendo. Si vas a correr el stack en un Mac usado como servidor por terminal, lee primero Runtime de Docker en macOS.
  • 4 GB de RAM y ~10 GB de disco libre.
  • Acceso al repositorio almirant-ai/almirant en GitHub. Mientras el repo sea privado, necesitas un metodo de autenticacion git funcional (ver Paso 1). Cuando el repo pase a publico este paso sera innecesario.
  • Una URL publica por la que se accedera al servicio. Puede ser:
    • http://localhost:8080 para uso local.
    • Un dominio propio con HTTPS.
    • Una URL de Tailscale Funnel (https://<host>.<tailnet>.ts.net).
    • La URL de un tunel (Cloudflare Tunnel, ngrok, etc.).

Runtime de Docker en macOS​

En macOS, Docker corre dentro de una VM Linux. El "runtime" es la app que gestiona esa VM. Hay tres opciones:

RuntimeMejor paraTradeoff
Docker DesktopDev en Mac con UI abiertaPesado (~500 MB en idle), requiere session GUI activa
OrbStackDev en Mac con UI abiertaMuy rapido, menubar app — requiere session GUI activa, paid para uso comercial
ColimaServidor headlessCLI puro, arranca como service de macOS — sobrevive reboots sin login GUI, gratis
Si usas el Mac como servidor (acceso solo por SSH)

Docker Desktop y OrbStack son apps de macOS que requieren que un usuario haya hecho login en la sesion grafica. Si el Mac reinicia y nadie se sienta a desbloquearlo, el daemon de Docker queda muerto y tu instancia tampoco arranca.

Para uso server, usa Colima:

brew install colima docker docker-compose

# Sizing tipico para un Mac de 16 GB / 8 cores
colima start --cpu 4 --memory 6 --disk 40

# Que arranque solo al boot (sin necesidad de login GUI)
colima stop
brew services start colima

Verifica que responde:

docker ps   # debe responder en menos de un segundo

Cambiar de runtime con datos existentes​

Cambiar de OrbStack/Desktop a Colima borra los volumenes (viven dentro de la VM del runtime viejo). Si ya tienes datos importantes:

  1. Con el runtime viejo vivo, exporta: pg_dump para Postgres, snapshot manual para Redis si lo usas.
  2. Apaga el stack: almirant down.
  3. Instala y arranca Colima.
  4. Cambia el contexto: docker context use colima.
  5. Vuelve a almirant install o almirant upgrade para crear los volumenes nuevos.
  6. Restaura los dumps.

Si la instancia es nueva o vacia, salta directo al Paso 1.

Paso 1 — Autenticar git contra GitHub​

info

Este paso desaparecera cuando el repo de Almirant se haga publico. Si estas leyendo esto despues de esa transicion, saltatelo.

El instalador hace git clone https://github.com/almirant-ai/almirant.git. Si el repo es privado, git pide credenciales. La forma mas limpia es usar gh:

# Instala gh si no lo tienes
brew install gh           # macOS
sudo apt install gh       # Debian/Ubuntu

# Login interactivo — elige protocolo HTTPS (no SSH)
gh auth login
# GitHub.com → HTTPS → Login with a web browser

# Configura git para usar las credenciales de gh
gh auth setup-git

Verifica que el credential helper de gh quedo configurado:

git config --global --get-all credential.https://github.com.helper
# Debe mostrar: !/opt/homebrew/bin/gh auth git-credential   (o similar)

Si en macOS ves errores tipo failed to get: -25308 durante el clone, tu Keychain esta bloqueado (tipico en sesiones SSH sin UI grafica). Desbloquealo:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Paso 2 — Instalar el CLI​

bun add -g almirant@latest
# o
npm i -g almirant

Paso 3 — Lanzar almirant install​

La forma mas recomendada es pasar --public-url desde el principio con la URL exacta por la que accederas al servicio:

almirant install --public-url https://almirant.miempresa.com
Por que importa la URL publica

almirant install baquea la URL publica en cuatro variables simultaneamente:

  • NEXT_PUBLIC_SITE_URL (compilada dentro del bundle del frontend)
  • BETTER_AUTH_URL
  • BETTER_AUTH_TRUSTED_ORIGINS
  • CORS_ORIGIN

Si mas tarde accedes desde una URL distinta (p. ej. pusiste http://localhost:8080 pero entras por https://mimac.tailnet.ts.net), Better-Auth rechaza la peticion con Invalid origin y el registro falla.

Cambiar la URL despues requiere un rebuild del frontend. Ver Cambiar la URL publica.

El instalador:

  1. Comprueba requisitos (Docker + Compose v2).
  2. Clona almirant-ai/almirant en ~/.almirant/stack (o hace fast-forward si ya existe).
  3. Genera .env.production con secretos aleatorios si no existe.
  4. Construye las imagenes Docker (backend, frontend, runner, db-init, shims…). La primera vez tarda 10-20 minutos.
  5. Arranca el stack con docker compose up -d.
  6. Espera a que el frontend este healthy.
  7. Imprime la URL final y los comandos de dia-2.

Flags importantes de install​

FlagCuando usarlo
--public-urlSiempre que puedas. Evita tener que rebuildear despues.
--non-interactiveScripts de CI o aprovisionamiento automatico.
--with-proxySi quieres el reverse proxy (Caddy) integrado, en lugar de exponer puertos directos.
--with-discordSi vas a usar el puente con Discord.
--branchPara fijar una version concreta (v1.2.3) en lugar de main.
--from-dirInstalaciones air-gapped desde un clone ya presente en disco.

Ver la lista completa en Referencia → install.

Paso 4 — Completar el onboarding​

Abre la URL que te imprimio el instalador. La primera visita te lleva a /signup.

  • Si la base de datos esta vacia (primer boot limpio), el formulario funciona en modo initial_admin_setup: el primer usuario registrado se crea con rol admin y es redirigido al wizard en /onboarding.
  • Si ya hay usuarios (por ejemplo porque reinstalaste reutilizando el mismo volumen de Postgres), el formulario funciona como signup normal: el usuario recien creado no es admin y va al dashboard. Si quieres forzar un primer admin limpio, ver Empezar de cero.

El wizard de /onboarding tiene tres pasos, todos con boton "Skip for now":

  1. Admin account — confirma que el primer administrador existe y cierra el registro abierto.
  2. Public URL (Tailscale) — puedes publicar la instancia con Tailscale Funnel o pegar una URL externa propia.
  3. GitHub App — crea una GitHub App con un manifest prerellenado o acepta credenciales ya existentes, para que los agentes puedan abrir PRs.

Al terminar, la app esta lista. El link a /onboarding queda visible en el sidebar hasta que completes todos los pasos.

Paso opcional — Proteger Postgres con Tailscale​

Por defecto, Postgres vive dentro de Docker y no debe exponerse en la interfaz publica del VPS. Si necesitas conectarte desde tu portatil con TablePlus, DBeaver, DataGrip o psql, la forma segura es crear un acceso privado por Tailscale.

La idea es esta:

  • Tu portatil entra en tu tailnet normal de Tailscale.
  • Almirant crea un nodo separado llamado, por defecto, almirant-db.
  • Ese nodo escucha solo en la red privada de Tailscale y reenvia el puerto 5432 al Postgres interno de Docker.
  • Postgres sigue sin publicarse en internet.
No abras Postgres en el firewall del VPS

No publiques 5432:5432 ni abras el puerto 5432 a internet "para probar". Eso funciona, pero es una mala base de seguridad. La base de datos debe quedar accesible solo desde dispositivos autorizados dentro de tu tailnet.

1. Prepara tu tailnet​

Primero instala Tailscale en tu portatil e inicia sesion. En el panel de Tailscale, verifica que tu maquina aparece en Machines.

Despues, en Access controls, declara un tag para el nodo de base de datos:

"tagOwners": {
  "tag:almirant-db": ["autogroup:admin"]
}

Si ya tienes tagOwners, no lo reemplaces entero: anade solo la entrada tag:almirant-db.

2. Limita quien puede llegar a Postgres​

Anade una regla que permita a tu usuario acceder al nodo de base de datos solo por TCP 5432:

"grants": [
  {
    "src": ["[email protected]"],
    "dst": ["tag:almirant-db"],
    "ip": ["tcp:5432"]
  }
]

Cambia [email protected] por el email con el que entras a Tailscale.

Empieza simple

Si estas empezando con Tailscale, usa una Auth Key. El flujo con OAuth client es mejor para automatizacion avanzada, pero anade conceptos que no hacen falta para la primera configuracion.

3. Crea una Auth Key para Almirant​

En Tailscale Admin:

  1. Ve a Keys.
  2. Pulsa Generate auth key.
  3. Usa una descripcion como Almirant DB.
  4. Activa el tag tag:almirant-db.
  5. Si tu tailnet requiere aprobacion de dispositivos, marca la key como pre-approved.
  6. Copia la key. Debe empezar por tskey-auth-....

No guardes esta key en el repositorio ni la pegues en issues, logs o capturas.

4. Conecta Almirant al tailnet​

En Almirant, entra como admin y ve a:

/settings/instance

En Private database access:

CampoValor recomendado
Hostnamealmirant-db
Tagtag:almirant-db
MetodoAuth key
Auth keyLa key tskey-auth-... de Tailscale

Pulsa Connect. Mientras este en provisioning, espera a que el estado pase a connected.

Cuando termine, Almirant mostrara una connection string parecida a:

postgresql://...@almirant-db.<tu-tailnet>.ts.net:5432/...

Usa esa URL desde tu portatil, estando conectado a Tailscale.

5. Checklist si no conecta​

Revisa en este orden:

  1. Tu portatil esta conectado a Tailscale.
  2. En Tailscale Admin aparece una maquina llamada almirant-db.
  3. Esa maquina tiene el tag tag:almirant-db.
  4. La regla de acceso permite tcp:5432 hacia tag:almirant-db.
  5. En Almirant, el estado de Private database access es connected.
  6. Estas usando la connection string que muestra Almirant, no el DATABASE_URL interno del contenedor.

Si MagicDNS no resuelve el hostname, usa temporalmente la IP Tailscale 100.x.y.z que muestra Almirant.

Paso 5 — Conectar el CLI contra tu instancia​

Hasta aqui has instalado el stack. Ahora toca configurar el CLI para que apunte a esa instancia y puedas hacer init / link en tus repos. Este paso se hace una vez por maquina desde la que vayas a usar el CLI (tu portatil, una VM de desarrollo, el servidor mismo, etc.).

5.1 — Identifica la URL del API​

La URL del API es tu --public-url con /api al final:

--public-url del installURL del API
https://almirant.miempresa.comhttps://almirant.miempresa.com/api
https://<host>.<tailnet>.ts.nethttps://<host>.<tailnet>.ts.net/api
http://localhost:8080http://localhost:8080/api

5.2 — Autentica el CLI​

Desde la maquina donde vayas a usar el CLI:

# Instala el CLI si aun no lo tienes en esa maquina
bun add -g almirant@latest

# Login contra tu instancia self-hosted
almirant login --api-url https://almirant.miempresa.com/api

Se abre el navegador contra tu instancia, autorizas la sesion, y el CLI captura una API key que guarda en ~/.almirant/config.json. La cuenta queda con ID estable y un label local que puedes renombrar.

Desde otra maquina

Este paso es independiente de donde corra el stack. Si el stack vive en un servidor remoto y quieres usar el CLI desde tu portatil, solo necesitas que tu portatil pueda acceder via HTTPS a la URL del API. Si esta detras de Tailscale, asegurate de estar en el mismo tailnet; si esta tras un tunel/proxy, que el puerto sea accesible.

5.3 — Verifica la configuracion​

almirant accounts list
almirant current

Deberias ver tu cuenta self-hosted listada, con API URL apuntando a tu instancia y la API key representada solo por su prefijo.

Si tienes varias cuentas (p. ej. tambien trabajas contra el SaaS de almirant.ai), ponles labels y elige cual es la activa:

almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro

Mas detalle en Trabajar con varias cuentas.

5.4 — Vincula un repositorio​

Con la cuenta autenticada, vincular un repo a un proyecto de tu instancia es identico al flujo SaaS:

cd mi-repo
almirant link
# Si tienes varias cuentas, elige la self-hosted
# Selecciona un proyecto o crea uno nuevo

El CLI escribe .mcp.json con almirant mcp proxy --project-id ... --account .... La API key no queda en el repo; vive en ~/.almirant/config.json y el proxy la adjunta en memoria.

El flujo completo paso a paso (con verificacion desde el IDE) esta en Conectar un repositorio.

Empezar de cero​

Si algo salio mal y quieres empezar con base de datos limpia (destruye todos los datos del stack local):

almirant down --volumes
almirant install --public-url https://almirant.miempresa.com
warning

almirant down --volumes borra los volumenes de Postgres y Redis. Solo usalo en instalaciones de test o cuando estes seguro de querer perder los datos.

Errores comunes en la primera instalacion​

password authentication failed for user "almirant"​

Significa que el volumen de Postgres tiene un password viejo de una instalacion anterior, distinto del que acaba de generarse en .env.production. Postgres solo lee POSTGRES_PASSWORD del env en el primer boot del volumen.

Fix: borra los volumenes y reinstala (ver Empezar de cero).

Invalid origin al registrarte​

La URL desde la que accedes no esta en BETTER_AUTH_TRUSTED_ORIGINS.

Fix: reinstala con --public-url igual a la URL exacta de la barra del navegador:

almirant install --public-url https://<lo-que-ves-en-tu-navegador>

Si ya tienes datos que no quieres perder, puedes cambiar la URL sin reinstalar: ver Cambiar la URL publica.

404 despues del signup​

Causa mas frecuente: tu usuario no tiene rol admin (la DB ya tenia usuarios de un intento previo) y el redirect lo manda a /board, que puede fallar si no hay proyectos creados aun.

Fix: empezar de cero para que tu primer registro sea en modo initial_admin_setup.

docker ps se queda colgado / sin respuesta​

El cliente Docker espera al socket del daemon. Si ese socket apunta a un runtime que no esta vivo, cuelga.

Diagnostico rapido:

docker context ls
# Mira que context tiene el `*` y a que socket apunta.

ls -la /var/run/docker.sock 2>&1
ls -la ~/.docker/run/docker.sock 2>&1
ls -la ~/.orbstack/run/docker.sock 2>&1
# El socket del context activo tiene que existir y tener permiso de escritura.

pgrep -lf -i 'OrbStack|Docker Desktop|colima' | head -5
# Tiene que aparecer al menos uno.

Fixes segun escenario:

  • Docker Desktop u OrbStack instalado pero la app esta cerrada → abrir la app: open -a OrbStack (o open -a "Docker Desktop"). Esperar 30-60 seg, reintentar docker ps.
  • App arrancada pero la VM esta zombie → cerrar y volver a abrir, o colima stop && colima start si usas Colima.
  • Cambiaste de runtime y el context apunta al viejo → docker context use colima (o el nombre correcto).
  • Mac usado como server y queres que sobreviva reboots → migra a Colima como service (ver Runtime de Docker en macOS).

lockfile had changes, but lockfile is frozen durante el build​

RUN bun install --frozen-lockfile
error: lockfile had changes, but lockfile is frozen

Pasa cuando el repo del stack introdujo un nuevo workspace de bun y algun Dockerfile no se actualizo para copiarlo al builder context. Es un bug del stack, no de tu instalacion.

Fix: git pull el repo del stack para tomar la version mas nueva (que ya incluye el fix), y reintentar:

cd ~/.almirant/stack
git pull --ff-only origin main
almirant upgrade

Si tu version del stack es anterior al fix y no podes actualizarla, pega manualmente la linea COPY services/<workspace>/package.json ./services/<workspace>/package.json en los Dockerfiles afectados antes del bun install.

Errores de Docker con keychain en macOS​

error getting credentials — err: exit status 1, out: keychain cannot be accessed aparece cuando operas por SSH en un Mac sin sesion grafica.

Fix rapido:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Fix permanente (solo si operas siempre via SSH):

# Desconecta Docker del keychain
jq 'del(.credsStore, .credHelpers)' ~/.docker/config.json > ~/.docker/config.json.tmp \
  && mv ~/.docker/config.json.tmp ~/.docker/config.json

Siguiente paso​

Stack corriendo, admin creado, onboarding cerrado. Para operar la instancia dia-a-dia (logs, upgrades, backups, cambios de URL), ve a Operar el stack.