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

Qué va a implementar

Iva es un asistente de IA para Telegram autoalojado. Es una de las pocas opciones que se pueden implementar sin abrir ningún puerto de entrada ni apuntar un dominio al servidor. Tampoco necesita un certificado, porque ningún servicio del servidor escucha conexiones públicas. El servicio inicia una conexión saliente a Telegram, la mantiene abierta y lee sus mensajes a través de esa conexión. Todo lo demás se basa en esa única conexión saliente.

Iva se distribuye con licencia MIT y está escrito en Node. Su memoria es una carpeta de archivos Markdown simples que Obsidian puede abrir directamente. Por eso, 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. Desde entonces, el repositorio cambió de nombre de smixs/iva a smixs/iva-agent, y los comandos siguientes usan el nombre nuevo.

La mayoría del software autoalojado empieza 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 protegida por un firewall que sólo permite SSH constituye 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 canaliza 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-agent/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 equipo tiene menos de 1.5 GB de RAM y no tiene intercambio, porque la compilación 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 agent-browser como paquete global de npm. Después descarga Chromium y coloca la CLI de Google Workspace, gws, en ~/.local sin sudo.
• 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 una sola línea. 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 ejecuta después con los privilegios que tenía el instalador. El script llama a sudo sólo para instalar los paquetes y crear el archivo de intercambio, y posiblemente una vez más durante el paso de Chromium, mediante un ayudante que ejecuta los comandos directamente cuando ya se está ejecutando como 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 el clonado. Así puede elegir la versión.

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

Ahora sabe qué código se está ejecutando. Eso no se sabe 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 git en un estado HEAD separado. Funciona correctamente, pero debe conocer el límite: iva update mueve el checkout a la rama de actualización, por lo que la fijación es un punto de partida conocido y no un bloqueo permanente. iva version muestra la versión del paquete y el commit de git, de modo que siempre puede comprobar en qué estado se encuentra.

Para pasar deliberadamente a una versión posterior, liste las etiquetas, haga checkout de la que haya elegido en lugar de v0.3.13 más abajo y vuelva a ejecutar el instalador desde dentro del checkout. El instalador no tiene ninguna opción para una etiqueta de versión. Sus variables de entorno documentadas son REPO_URL, BRANCH y INSTALL_DIR, por lo que el checkout de git es el único mecanismo que fija la versión.

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

--skip-setup impide que el asistente vuelva a ejecutarse sobre un .env que ya funciona. Después, ejecute iva version para confirmar el commit en el que ha quedado.

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": 10
  },
  {
    "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": 15
  }
]

Estos son precios de lista publicados a octubre de 2026, no mediciones. Un VPS pequeño por 5 dólares estadounidenses más el plan OpenCode Go por 10 dólares es la configuración completa más económica, con un coste aproximado de 15 dólares al mes. La página de Go de OpenCode indica ese precio mensual sin descuento durante el primer mes, y el README de Iva sitúa la misma configuración en unos 14 a 15 dólares en total. Ollama Cloud es la otra opción de tarifa fija: 20 dólares por su plan Pro. El uso que supere los créditos incluidos en el plan se factura aparte. 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 del consumo. Es la opción que debe vigilar: un asistente que mantiene 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 inflado 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 sondeo largo: iva-telegram-poll.service llama a getUpdates y espera, por lo que todas las conexiones salen de tu servidor. Nada tiene que llegar al servidor desde el exterior, así que no necesitas un registro DNS ni un certificado. El puerto HTTP propio del agente, 8723, está enlazado a 127.0.0.1, y la documentación del proyecto indica que no debes exponerlo. Un firewall que permita SSH y nada más es la configuración correcta.

¿Cuánto cuesta ejecutar Iva cada mes?

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

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

De forma predeterminada, en ~/iva/vault, configurado mediante ASSISTANT_VAULT_DIR. Es un repositorio git privado independiente que contiene markdown sin formato: CORE.md, daily/YYYY-MM-DD.md, cards/ y summaries/. El doctor de memoria de las 05:00 hace commit y push, pero esto sólo sirve si el repositorio tiene un remoto, así que ejecuta gh auth login o añade tu propio remoto durante la configuración. Conserva también una copia sin conexión con tar czf ~/iva-vault-backup.tgz -C ~/iva vault y mueve ese archivo fuera del servidor.

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

El almacenamiento es tuyo. El procesamiento no. La bóveda permanece en tu disco hasta que haces push, y .env tiene el modo 0600 y pertenece al usuario del servicio. Las llamadas al modelo y la transcripción de voz son APIs en la nube, por lo que esos mensajes pasan por tu proveedor del modelo y por Deepgram. Iva usa la licencia MIT, así que puedes leer exactamente lo que envía y modificarlo. La lista de permitidos de Telegram aplica una política de denegación predeterminada: un TELEGRAM_ALLOWED_USER_IDS vacío bloquea a todo el mundo, incluido tú.

¿Qué proveedores de modelos admite Iva?

En la versión v0.3.13 fijada, MODEL_PROVIDER acepta opencode (OpenCode Go), ollama (Ollama Cloud), openrouter y codex. OpenRouter usa un identificador de proveedor como anthropic/claude-sonnet-4.5 y ofrece la mayor variedad de modelos. codex inicia sesión en una suscripción existente de ChatGPT mediante iva login y no utiliza ninguna API key. Las versiones posteriores añaden más rutas, incluida una suscripción de Claude y un endpoint compatible con OpenAI personalizado. Configura el proveedor y la ventana de contexto correspondiente con el tamaño real del modelo. Después ejecuta iva restart, porque el modelo se lee una sola vez al iniciar el proceso.