Cómo autohospedar Iva, un asistente de IA para Telegram

Qué va a crear

Iva es un asistente de IA de Telegram autohospedado. Es una de las pocas opciones que puede implementar sin abrir ningún puerto entrante ni asociar un dominio. Tampoco necesita un certificado, porque ningún servicio del servidor escucha conexiones públicas. El servicio inicia una conexión saliente con Telegram, la mantiene abierta y lee los mensajes recibidos en la respuesta. Todo lo demás se basa en esa única conexión saliente.

Iva usa la licencia MIT y está escrito en Node. Su memoria es una carpeta de archivos Markdown sin formato que Obsidian abre directamente. Por tanto, las notas que guarda sobre usted siguen siendo legibles sin la aplicación. Esta guía fija la versión v0.3.13, publicada el 6 de agosto de 2026.

La mayoría del software autohospedado comienza con un registro DNS (sistema de nombres de dominio) y un certificado de Let's Encrypt emitido con Certbot. Iva omite por completo esa capa. Por eso, una VPS pequeña detrás de un firewall que sólo permita SSH es una implementación completa.

Por qué Iva no necesita puertos abiertos

iva-telegram-poll.service es un puente de sondeo largo. Llama a la API de getUpdates de Telegram y espera la respuesta, por lo que cada conexión se inicia desde el servidor. Telegram nunca se conecta de vuelta. Por tanto, no hay ningún reverse proxy que configurar ni certificados cuya renovación pueda olvidarse.

El agente sí escucha, pero sólo en el puerto 127.0.0.1 8723. La documentación del proyecto lo indica claramente: no exponga el puerto 8723 y, si coloca un reverse proxy delante, debe mantener el requisito del bearer token. Compruebe la dirección de enlace después de la instalación.

sudo ss -tlnp | grep 8723

La dirección debe ser 127.0.0.1:8723. Una dirección comodín como 0.0.0.0:8723 permite acceder desde Internet a las rutas HTTP del agente. Corríjalo antes de enviar al bot cualquier dato privado.

Por tanto, el firewall permanece cerrado. Permita SSH antes de activarlo, porque ufw enable sin una regla para SSH cerrará la sesión en la que está escribiendo.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Qué hace realmente el instalador de una sola línea

La página principal del proyecto proporciona un comando que pasa un script de GitHub a bash. Lea primero el script, porque hace mucho más que instalar un solo programa.

curl -fsSL https://raw.githubusercontent.com/smixs/iva/main/install.sh -o iva-install.sh
less iva-install.sh

• Instala paquetes del sistema con el gestor de paquetes detectado: git, gh, python3, ffmpeg, pandoc y poppler-utils.
• Crea un archivo de intercambio de 2 GB en /swapfile cuando el sistema tiene menos de 1.5 GB de RAM y no tiene intercambio, porque la compilación se termina sin él.
• Instala nvm y después Node 24, que es la versión mínima que necesita Iva.
• Instala uv, el gestor de paquetes de Python, en ~/.local/bin.
• Clona el repositorio en ~/iva y ejecuta npm ci.
• Instala dos paquetes npm globales, agent-browser, que después descarga Chromium, y @googleworkspace/cli.
• Ejecuta el asistente de configuración, compila el proyecto y crea el almacén.
• Escribe un comando iva en ~/.local/bin e instala las unidades de usuario de systemd.

Es mucho software para un solo comando. Esto también explica la instrucción del README de instalarlo como un usuario normal y no como root: la herramienta de shell del agente se ejecutará después con los privilegios que tenía el instalador. El script sólo llama a sudo para instalar los paquetes y crear el archivo de intercambio, mediante un ayudante que ejecuta los comandos directamente cuando ya se está usando root.

Cree un usuario dedicado antes de instalar

Asigne a Iva su propia cuenta. El agente ejecuta comandos de shell en el host mediante child_process de Node, sin contenedor ni sandbox, por lo que la cuenta con la que se ejecuta es el límite de seguridad.

sudo adduser --disabled-password --gecos "" iva
sudo usermod -aG sudo iva
sudo install -d -m 700 -o iva -g iva /home/iva/.ssh
sudo cp ~/.ssh/authorized_keys /home/iva/.ssh/authorized_keys
sudo chown iva:iva /home/iva/.ssh/authorized_keys
sudo chmod 600 /home/iva/.ssh/authorized_keys
sudo loginctl enable-linger iva

enable-linger es importante porque Iva se ejecuta como unidades de usuario de systemd. Sin linger, systemd detiene los servicios de ese usuario en cuanto termina su última sesión, por lo que el asistente se cerraría al salir de SSH. La misma regla se aplica a cualquier servicio y temporizador que escriba usted mismo en systemd.

La cuenta necesita sudo sólo mientras el instalador añade paquetes. Retírelo cuando termine la instalación.

sudo deluser iva sudo

Inicie sesión directamente con ese usuario mediante SSH. Un shell abierto con sudo -iu iva no tiene definidos DBUS_SESSION_BUS_ADDRESS ni XDG_RUNTIME_DIR, por lo que todos los comandos systemctl --user fallan con Failed to connect to bus. Establecer este límite aplica el mismo principio que ejecutar servicios con usuarios con privilegios mínimos.

Instale una versión fijada en lugar de canalizarla a bash

El instalador tiene una propiedad útil. Antes de clonar nada, comprueba si el directorio donde se encuentra el script ya contiene un package.json con "eve". Si lo contiene, compila ese checkout y omite la clonación. Así puede elegir la versión.

git clone --branch v0.3.13 https://github.com/smixs/iva.git ~/iva
cd ~/iva
git log -1 --oneline
bash install.sh

Ahora sabe qué código se está ejecutando. No puede saberlo cuando el script clona main en el estado que tenga en ese momento. Iva publicó cinco versiones entre el 4 y el 6 de agosto de 2026, por lo que main esta mañana y main esta tarde no son el mismo programa.

Un checkout de una etiqueta deja a git en estado HEAD separado. Funciona correctamente, pero debe conocer la limitación: iva update mueve el checkout a la rama de actualización, por lo que la fijación define un punto de partida conocido, no un bloqueo permanente. iva version muestra la versión del paquete y el commit de git, de modo que siempre puede saber en qué estado se encuentra.

Para pasar deliberadamente a una versión posterior, liste las etiquetas, establezca IVA_TAG en la que haya elegido y vuelva a ejecutar el instalador desde dentro del checkout.

cd ~/iva
git fetch --tags
git tag --list 'v*' | sort -V | tail -5
IVA_TAG=v0.3.13
git checkout "$IVA_TAG"
bash install.sh --skip-setup
iva restart

--skip-setup evita que el asistente se vuelva a ejecutar sobre un .env que ya funciona.

Los cinco pasos del asistente y las claves que solicita

1. Proveedor y modelo. MODEL_PROVIDER acepta opencode, ollama, openrouter o codex. El asistente valida la clave en tiempo real y muestra los modelos que ofrece su plan.
2. Voz y búsqueda. Una clave de Deepgram transcribe las notas de voz. Una clave de búsqueda web (Tavily, Exa, Parallel o Brave) es opcional.
3. Token del bot de Telegram obtenido de @BotFather, comprobado contra el endpoint getMe.
4. Control de acceso. Envíe un mensaje a su bot y el asistente extraerá su ID de usuario numérico de getUpdates.
5. Configuración del sistema. Zona horaria IANA, directorio de la bóveda y puerto local, 8723 de forma predeterminada.

Dos de estos elementos son dependencias que el enfoque de «un solo comando» oculta. Iva no incluye ningún modelo, por lo que necesita un plan de modelos de pago o una clave de API antes de responder. Tampoco transcribe audio por sí mismo, así que las notas de voz necesitan un servicio independiente. El modelo nova-3 de Deepgram con DEEPGRAM_LANGUAGE=multi detecta el idioma, y las cuentas nuevas de Deepgram reciben créditos iniciales que cubren meses de uso personal. El texto funciona sólo con la clave del modelo. Deepgram sólo es necesario para la voz.

Compruebe lo que escribió el asistente.

grep -E '^(MODEL_PROVIDER|TELEGRAM_ALLOWED_USER_IDS|ASSISTANT_VAULT_DIR|IVA_PORT)=' ~/iva/.env
ls -l ~/iva/.env

ls debe mostrar -rw-------, con modo 0600, porque ese archivo contiene todas las claves que acaba de pegar. TELEGRAM_ALLOWED_USER_IDS debe contener su ID numérico. La lista de permitidos aplica una política de denegación predeterminada, por lo que un valor vacío significa que Iva no responde a nadie.

El modelo se lee una sola vez, al iniciar el proceso. Editar MODEL_PROVIDER o el nombre del modelo en .env no cambia nada hasta que ejecute iva restart. En openrouter, el nombre del modelo es un identificador del proveedor, como anthropic/claude-sonnet-4.5, no un nombre simple. En codex no hay ninguna clave de API: iva login inicia sesión en una suscripción existente de ChatGPT.

Cuánto cuesta ejecutar Iva cada mes

[
  {
    "plan": "Small VPS, always on",
    "usd_per_month": 5
  },
  {
    "plan": "OpenCode Go model plan",
    "usd_per_month": 5
  },
  {
    "plan": "Ollama Cloud model plan",
    "usd_per_month": 20
  },
  {
    "plan": "Deepgram voice, starter credits",
    "usd_per_month": 0
  },
  {
    "plan": "Tavily web search, free tier",
    "usd_per_month": 0
  },
  {
    "plan": "Cheapest complete setup",
    "usd_per_month": 10
  }
]

Estos son precios de lista publicados en agosto de 2026, no mediciones. Un VPS pequeño de 5 dólares estadounidenses más el plan OpenCode Go de 5 dólares es la configuración completa más barata: cuesta aproximadamente 10 dólares al mes. Ollama Cloud es la otra opción con tarifa fija, de 20 dólares, y sus modelos frontier facturan el uso adicional aparte del plan. La voz cuesta 0 mientras duren los créditos iniciales de Deepgram.

OpenRouter no aparece aquí porque funciona con pago por uso, por lo que la factura depende de su consumo. Es la opción que debe vigilar: un asistente que utiliza una ventana de contexto de 131072 tokens en cada turno puede superar rápidamente el coste de un plan fijo. Configure la variable de la ventana de contexto con el tamaño real del modelo, porque un valor demasiado alto sólo desperdicia tokens.

Los dos servicios y los dos temporizadores

• iva.service ejecuta el agente.
• iva-telegram-poll.service ejecuta el puente de sondeo largo que se comunica con Telegram.
• iva-memory-doctor.timer se activa a las 05:00 y ejecuta la tarea de mantenimiento nocturno en el almacén.
• iva-update-check.timer se activa a las 10:00 y comprueba si existe una versión más reciente.
• iva-telegram-userbot.service sólo existe si configuró el proxy opcional de Telethon.

iva status
systemctl --user status iva.service iva-telegram-poll.service
systemctl --user list-timers
iva logs poll

iva status muestra el estado de los dos servicios y de los dos temporizadores de supervisión. systemctl --user list-timers muestra la próxima hora de ejecución de cada temporizador. Así puede confirmar que el doctor de memoria se ejecutará esta noche. Ambos servicios deben permanecer en active (running). Si uno se reinicia continuamente, journalctl --user -u iva.service -n 100 muestra el motivo.

La separación es importante al depurar. El puente puede estar activo y sondeando mientras el agente está detenido. En ese caso, Telegram acepta el mensaje, pero nunca recibe una respuesta. iva logs poll supervisa el puente y iva logs supervisa el agente. Así, los dos registros indican qué parte está fallando.

Dónde se encuentra el vault de Obsidian y cómo hacer una copia de seguridad

ASSISTANT_VAULT_DIR tiene el valor predeterminado vault dentro del directorio de instalación, por lo que la memoria se encuentra en ~/iva/vault. Es un repositorio de git independiente del código. Esto permite actualizar Iva sin modificar las notas.

• vault/CORE.md contiene hechos permanentes y preferencias persistentes, con un límite de 1200 caracteres, y se incluye en cada prompt del sistema.
• vault/daily/YYYY-MM-DD.md es la transcripción del día y se trata como un archivo de solo adición.
• vault/cards/ contiene tarjetas tipadas para contactos, proyectos, decisiones, ideas y notas.
• vault/summaries/daily/, weekly/, monthly/ y yearly/ contienen los resúmenes acumulados.
• vault/attachments/ contiene archivos organizados por fecha, y vault/.graph/ contiene el grafo de enlaces.
• vault/schema.json define los tipos de tarjetas y las reglas de decaimiento.

Los resúmenes acumulados se generan según un horario dentro del proceso. La ejecución diaria de las 04:00 convierte la transcripción del día anterior en tarjetas y un resumen, y reescribe CORE.md. Después, las ejecuciones semanales, mensuales y anuales comprimen esos datos sucesivamente. A las 05:00, memory doctor ejecuta un proceso determinista que no utiliza ningún modelo: aplica el esquema, reconstruye el grafo de enlaces, vuelve a generar el índice y después hace commit y push.

Ese push es la copia de seguridad. Es el paso que suele omitirse. Si el vault no tiene un remoto de git, doctor intenta crear un repositorio privado de GitHub mediante gh. Para ello necesita un GitHub CLI autenticado.

gh auth login
systemctl --user start iva-memory-doctor.service
cd ~/iva/vault && git log --oneline -3

Un commit con la fecha de hoy indica que el proceso se ejecutó y que el vault tiene un commit. Las advertencias gh not available del registro indican lo contrario: el vault se mantiene, pero nunca sale del servidor. Por tanto, un VPS averiado se lleva la memoria consigo.

Conserve también una copia bajo su control.

tar czf ~/iva-vault-backup.tgz -C ~/iva vault

Copie ese archivo fuera del servidor con scp y después elimínelo del servidor. Para leer la memoria en Obsidian, indique a Obsidian que use un clon del repositorio del vault. Los Wikilinks y los backlinks funcionan sin cambios, al igual que la vista de grafo. Es seguro editar manualmente las tarjetas y CORE.md. No modifique MOC.md ni .graph/, porque la ejecución nocturna vuelve a generar ambos.

Trata el vault como un registro de tu vida

Ese directorio es un registro fechado de lo que dijiste, de las personas que conociste y de las decisiones que tomaste, en una máquina que alquilas. De aquí se derivan dos aspectos.

El self-hosting mueve el almacenamiento, no el procesamiento. Cada interacción llega a tu proveedor de modelos y cada nota de voz llega a Deepgram. El vault es tuyo. Las solicitudes no son privadas para las empresas que las procesan. Ejecutar tú mismo la capa de memoria, como con un servidor de memoria Mem0 en tu propio VPS, tiene la misma estructura: el almacenamiento es local, pero la llamada al modelo sigue saliendo de tu servidor. Si un asunto es demasiado sensible para un tercero, no lo incluyas en el chat.

El alcance de esa cuenta abarca todo el vault. Las herramientas de Iva se ejecutan de forma nativa en el host mediante fs y child_process de Node, sin Docker ni sandbox, por lo que una interacción secuestrada tiene el acceso de la cuenta de servicio. Por eso la cuenta no conserva ningún sudo después de la instalación y por eso la allowlist merece más atención de la que parece: es la puerta que decide qué mensajes se convierten en comandos en tu servidor. Si quieres llevar el asistente contigo sin exponer nada, este es el mismo patrón que se usa para acceder desde el teléfono a un agente Hermes autoalojado, donde el cliente de chat realiza la función que, de otro modo, tendría un endpoint público.

Qué falla y qué mensaje verá

Compilación terminada, código de salida 137. El asesino de procesos por falta de memoria del kernel terminó la compilación. El instalador sólo añade swap cuando la RAM es inferior a 1.5 GB y no existe swap, así que añádalo manualmente y vuelva a ejecutar el instalador.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
free -h

Failed to connect to bus. Todos los comandos de systemctl --user muestran este mensaje cuando el shell no tiene un bus de sesión de usuario, que es lo que proporciona sudo -iu iva. Abra una sesión SSH normal con ese usuario o exporte XDG_RUNTIME_DIR=/run/user/$(id -u iva) antes de ejecutar el comando.

El bot no responde. TELEGRAM_ALLOWED_USER_IDS está vacío y la lista de permitidos aplica una política de denegación predeterminada. Envíe un mensaje al bot: responderá con su ID numérico y nada más. Añada ese ID a .env y ejecute iva restart.

El bot deja de responder justo después de iva config. El asistente puede mover IVA_PORT sin actualizar ASSISTANT_HOST, por lo que el puente se conecta a un puerto en el que no responde ningún proceso. Compare las dos líneas y reinicie.

grep -E '^(IVA_PORT|ASSISTANT_HOST)=' ~/iva/.env
iva restart

Una nota de voz no recibe respuesta. Telegram's Bot API rechaza las descargas de archivos de más de 20 MB, por lo que el puente nunca recibe los audios largos y no tiene nada que enviar a Deepgram. Divida el archivo antes de enviarlo.

ffmpeg -i long.ogg -f segment -segment_time 600 -c copy part-%02d.ogg

Un turno se queda bloqueado y nunca responde. El estado atascado del flujo de trabajo sobrevive al reinicio y vuelve a ponerse en cola, por lo que reiniciar por sí solo no lo elimina. iva reset pone ese estado en cuarentena y reinicia ambos servicios. /new en el chat inicia una conversación nueva.

Chromium falla en Ubuntu 24.04. Ubuntu 24.04 bloquea los espacios de nombres de usuario sin privilegios mediante AppArmor, por lo que el sandbox propio de Chromium no puede iniciarse y agent-browser falla. El instalador evita el problema escribiendo "--no-sandbox" en ~/.agent-browser/config.json. Tenga en cuenta que esta configuración está presente. Reduce el aislamiento del navegador, lo que constituye otra razón para que la cuenta no sea propietaria de nada salvo Iva.

FAQ

¿Necesito un dominio o un puerto abierto para alojar Iva por mi cuenta?

No. Iva se comunica con Telegram mediante long polling: iva-telegram-poll.service llama a getUpdates y espera, por lo que todas las conexiones son salientes desde el servidor. No es necesario que nada llegue al servidor desde el exterior. Por tanto, no necesita un registro DNS ni un certificado. El puerto HTTP propio del agente, 8723, se enlaza a 127.0.0.1, y la documentación del proyecto indica que no debe exponerse. La configuración correcta es un firewall que permita SSH y nada más.

¿Cuánto cuesta ejecutar Iva al mes?

Con los precios de lista publicados en agosto de 2026, un VPS pequeño de 5 dólares más el plan de modelo de tarifa plana más barato, de 5 dólares, suman aproximadamente 10 dólares estadounidenses al mes. Ollama Cloud cuesta 20 dólares en su lugar y factura aparte los modelos avanzados. Los créditos iniciales de Deepgram cubren la voz al principio, y los niveles de búsqueda web tienen cuotas gratuitas. OpenRouter funciona mediante pago por uso, por lo que no tiene un importe mensual fijo.

¿Dónde guarda Iva mis datos y cómo hago una copia de seguridad?

De forma predeterminada, los guarda en ~/iva/vault, definido por ASSISTANT_VAULT_DIR. Es un repositorio git privado independiente con archivos markdown sin formato: CORE.md, daily/YYYY-MM-DD.md, cards/ y summaries/. El proceso memory doctor de las 05:00 hace commit y push del repositorio. Esto sólo sirve si el repositorio tiene un remoto, por lo que debe ejecutar gh auth login o añadir un remoto propio durante la configuración. Mantenga también una copia sin conexión con tar czf ~/iva-vault-backup.tgz -C ~/iva vault y transfiera ese archivo fuera del servidor.

¿Son privados mis datos si alojo Iva por mi cuenta?

El almacenamiento es suyo. El procesamiento no. El vault permanece en su disco hasta que lo envía mediante push, y .env tiene el modo 0600 y pertenece al usuario del servicio. Las llamadas a modelos y la transcripción de voz usan APIs en la nube, por lo que esos mensajes pasan por su proveedor de modelos y por Deepgram. Iva tiene licencia MIT, así que puede leer exactamente qué envía y modificarlo. La allowlist de Telegram aplica una política de denegación predeterminada: un TELEGRAM_ALLOWED_USER_IDS vacío bloquea a todos, incluido usted.

¿Qué proveedores de modelos admite Iva?

MODEL_PROVIDER acepta opencode (OpenCode Go), ollama (Ollama Cloud), openrouter y codex. OpenRouter utiliza un identificador de proveedor como anthropic/claude-sonnet-4.5 y ofrece la selección más amplia de modelos. codex inicia sesión en una suscripción existente de ChatGPT mediante iva login y no usa ninguna API key. Configure el proveedor y establezca la ventana de contexto correspondiente con el tamaño real del modelo. Después ejecute iva restart, porque el modelo se lee una sola vez al iniciar el proceso.