Como hospedar o Iva, assistente de IA no Telegram

O que está a construir

Iva é um assistente de IA para Telegram alojado pelo próprio utilizador. É uma das poucas opções que pode implementar sem abrir uma porta de entrada e sem apontar um domínio para o servidor. Também não existe certificado, porque nenhum serviço no servidor escuta ligações públicas. O serviço estabelece uma ligação de saída para o Telegram, mantém essa ligação aberta e lê as suas mensagens através da resposta. Todo o resto resulta dessa única ligação de saída.

Iva é licenciado ao abrigo da licença MIT e foi escrito em Node. A memória consiste numa pasta com ficheiros Markdown simples que o Obsidian abre diretamente. Assim, as notas que mantém sobre si continuam legíveis sem a aplicação. Este guia fixa a release v0.3.13, publicada em 6 August 2026.

A maioria do software alojado pelo próprio utilizador começa com um registo DNS (domain name system) e um certificado Let's Encrypt emitido com Certbot. Iva ignora completamente essa camada. Por isso, um VPS pequeno atrás de uma firewall que permite apenas SSH constitui uma implementação completa.

Por que o Iva não precisa de portas abertas

iva-telegram-poll.service é uma ponte de long polling. Ela chama a API getUpdates do Telegram e aguarda a resposta, portanto cada ligação é iniciada pelo seu servidor. O Telegram nunca liga de volta. Não é necessário configurar um reverse proxy nem lembrar-se de renovar certificados.

O próprio agente fica à escuta, mas apenas na porta 8723 de 127.0.0.1. A documentação do projeto é clara: não exponha a porta 8723, e qualquer reverse proxy colocado à frente do agente deve manter o requisito do bearer token. Verifique o endereço de escuta depois da instalação.

sudo ss -tlnp | grep 8723

O endereço deve ser 127.0.0.1:8723. Um endereço curinga, como 0.0.0.0:8723, significa que as rotas HTTP do agente estão acessíveis a partir da Internet. Corrija isso antes de enviar qualquer informação privada ao bot.

Assim, o firewall permanece fechado. Permita SSH antes de o ativar, porque ufw enable sem uma regra para SSH encerra a sessão que está a utilizar.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

O que o instalador de uma linha realmente faz

A página principal do projeto fornece um comando que envia um script do GitHub para o bash através de um pipe. Leia primeiro o script, porque ele faz muito mais do que instalar um único programa.

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

• Instala pacotes do sistema com o gestor de pacotes detetado: git, gh, python3, ffmpeg, pandoc e poppler-utils.
• Cria um ficheiro de swap de 2 GB em /swapfile quando o servidor tem menos de 1.5 GB de RAM e não tem swap, porque a compilação é terminada sem esse recurso.
• Instala o nvm e, depois, o Node 24, que é a versão mínima em que o Iva é executado.
• Instala uv, o gestor de pacotes Python, em ~/.local/bin.
• Clona o repositório para ~/iva e executa npm ci.
• Instala dois pacotes npm globais, agent-browser, que depois descarrega o Chromium, e @googleworkspace/cli.
• Executa o assistente de configuração, compila o projeto e cria o vault.
• Escreve um comando iva em ~/.local/bin e instala as unidades de utilizador do systemd.

É muito software para uma única linha. Isto também explica a instrução do README para instalar como um utilizador comum e não como root: posteriormente, a ferramenta de shell do agente é executada com os privilégios que o instalador tinha. O script chama sudo apenas para instalar pacotes e criar o ficheiro de swap, através de um auxiliar que executa os comandos diretamente quando já está a ser executado como root.

Crie um utilizador dedicado antes da instalação

Dê à Iva uma conta própria. O agente executa comandos shell no host através de child_process do Node, sem contentor nem sandbox. Por isso, a conta usada pelo agente é o limite de segurança.

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 é importante porque a Iva é executada como unidades user do systemd. Sem o linger, o systemd para os serviços desse utilizador assim que termina a última sessão. Assim, o assistente seria encerrado quando fechasse o SSH. A mesma regra aplica-se a qualquer serviço e temporizador que escreva manualmente no systemd.

A conta precisa de sudo apenas enquanto o instalador adiciona pacotes. Remova-o quando a instalação terminar.

sudo deluser iva sudo

Inicie sessão diretamente como esse utilizador através de SSH. Uma shell iniciada com sudo -iu iva não tem DBUS_SESSION_BUS_ADDRESS nem XDG_RUNTIME_DIR definidos. Por isso, todos os comandos systemctl --user falham com Failed to connect to bus. Criar este limite é o mesmo que executar serviços com utilizadores com privilégios mínimos.

Instalar uma versão fixa em vez de enviar o conteúdo diretamente para o bash

O instalador tem uma propriedade útil. Antes de clonar qualquer conteúdo, verifica se o diretório onde o script está localizado já contém um package.json com "eve". Se contiver, compila essa cópia local e ignora a clonagem. Assim, pode escolher a versão.

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

Agora sabe qual código está em execução. Isso não é possível quando o script clona main no estado em que estiver naquele momento. A Iva lançou cinco versões entre 4 e 6 de agosto de 2026, portanto main esta manhã e main esta tarde não são o mesmo programa.

Uma cópia de uma tag deixa o git no estado detached HEAD. Isso funciona, mas é importante conhecer a limitação: iva update move a cópia para a frente, colocando-a no branch de atualização. Assim, a versão fixa é um ponto de partida conhecido, não um bloqueio permanente. iva version mostra a versão do pacote e o commit do git, para que possa verificar sempre o estado atual.

Para mudar deliberadamente para uma versão posterior, liste as tags, defina IVA_TAG com a tag escolhida e execute novamente o instalador dentro da cópia local.

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 impede que o assistente seja executado novamente sobre um .env que já funciona.

As cinco etapas do assistente e as chaves solicitadas

1. Provedor e modelo. MODEL_PROVIDER aceita opencode, ollama, openrouter ou codex. O assistente valida a chave em tempo real e lista os modelos disponíveis no seu plano.
2. Voz e pesquisa. Uma chave Deepgram transcreve notas de voz. Uma chave de pesquisa na Web (Tavily, Exa, Parallel ou Brave) é opcional.
3. Token do bot do Telegram obtido no @BotFather, validado no endpoint getMe.
4. Controlo de acesso. Envie uma mensagem ao seu bot, e o assistente lê o seu ID de utilizador numérico a partir de getUpdates.
5. Definições do sistema. Fuso horário IANA, diretório do cofre e porta local, 8723 por predefinição.

Duas dessas dependências ficam ocultas pela ideia de "um comando". O Iva não inclui nenhum modelo, por isso precisa de um plano de modelo pago ou de uma chave de API antes de responder. Também não transcreve áudio por si só, por isso as notas de voz precisam de um serviço separado. O modelo nova-3 da Deepgram, com DEEPGRAM_LANGUAGE=multi, deteta o idioma, e as novas contas Deepgram recebem créditos iniciais que cobrem meses de utilização pessoal. O texto funciona apenas com a chave do modelo. Só a voz depende da Deepgram.

Verifique o que o assistente gravou.

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

ls deve apresentar -rw-------, com o modo 0600, porque esse ficheiro contém todas as chaves que acabou de colar. TELEGRAM_ALLOWED_USER_IDS deve conter o seu ID numérico. A lista de permissões adota uma política de falha fechada, por isso um valor vazio significa que o Iva não responde a ninguém.

O modelo é lido uma vez, no arranque do processo. Editar MODEL_PROVIDER ou um nome de modelo em .env não altera nada até executar iva restart. Em openrouter, o nome do modelo é um identificador do fornecedor, como anthropic/claude-sonnet-4.5, e não um nome simples. Em codex não existe nenhuma chave de API: iva login inicia sessão numa subscrição ChatGPT existente.

Quanto custa executar o Iva por mês

[
  {
    "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
  }
]

Estes são preços de tabela publicados em agosto de 2026, não medições. Um VPS pequeno a 5 dólares americanos, mais o plano OpenCode Go a 5 dólares, é a configuração completa mais barata, por cerca de 10 dólares por mês. Ollama Cloud é a outra opção de preço fixo, a 20 dólares, e os seus modelos de fronteira são cobrados como utilização adicional além do plano. A voz custa 0 enquanto durarem os créditos iniciais da Deepgram.

O OpenRouter não tem uma linha aqui porque funciona com cobrança conforme o uso, por isso a fatura acompanha o seu consumo. Esta é a opção que deve monitorizar: um assistente que transporta uma janela de contexto de 131072 tokens para cada interação pode ultrapassar rapidamente o custo de um plano fixo. Defina a variável da janela de contexto para o tamanho real do modelo, porque um valor inflacionado apenas desperdiça tokens.

Os dois serviços e os dois timers

• iva.service executa o próprio agente.
• iva-telegram-poll.service executa a bridge de long polling que comunica com o Telegram.
• iva-memory-doctor.timer é acionado às 05:00 e executa a manutenção noturna do vault.
• iva-update-check.timer é acionado às 10:00 e verifica se existe uma versão mais recente.
• iva-telegram-userbot.service existe apenas se configurar o proxy Telethon opcional.

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

iva status mostra o estado dos dois serviços e dos dois timers de monitorização. systemctl --user list-timers mostra a próxima execução de cada timer. É assim que confirma que o memory doctor será executado esta noite. Os dois serviços devem permanecer em active (running). Se um deles reiniciar continuamente, journalctl --user -u iva.service -n 100 mostra o motivo.

Esta separação é importante para a depuração. A bridge pode estar ativa e a fazer polling enquanto o agente está parado. Nesse caso, o Telegram aceita a sua mensagem, mas nada responde. iva logs poll acompanha a bridge. iva logs acompanha o agente. Assim, os dois logs mostram qual das partes está com problemas.

Onde o vault do Obsidian fica e como fazer backup

ASSISTANT_VAULT_DIR usa vault por padrão dentro do diretório de instalação, portanto a memória fica em ~/iva/vault. É um repositório git próprio, separado do código. Isso permite atualizar o Iva sem alterar as suas notas.

• vault/CORE.md contém factos persistentes e preferências permanentes, com um limite de 1200 caracteres, e é incluído em todos os prompts do sistema.
• vault/daily/YYYY-MM-DD.md é a transcrição do dia e é tratada apenas para acréscimos.
• vault/cards/ contém cartões tipados para contactos, projetos, decisões, ideias e notas.
• vault/summaries/daily/, weekly/, monthly/ e yearly/ contêm os rollups.
• vault/attachments/ contém ficheiros organizados por data, e vault/.graph/ contém o grafo de ligações.
• vault/schema.json define os tipos de cartões e as regras de decaimento.

Os rollups são executados de acordo com um agendamento dentro do processo. A execução diária, às 04:00, transforma a transcrição do dia anterior em cartões e num resumo e reescreve CORE.md. Em seguida, as execuções semanais, mensais e anuais comprimem esses dados sucessivamente. Às 05:00, o memory doctor executa uma operação determinística sem envolver um modelo: aplica o schema, recria o grafo de ligações, regenera o índice e depois faz commit e push.

Esse push é o seu backup. É também a etapa que muitas pessoas esquecem. Se o vault não tiver um git remote, o doctor tenta criar um repositório privado no GitHub através de gh, o que requer um GitHub CLI autenticado.

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

Um commit com a data de hoje significa que a execução ocorreu e que o vault foi submetido a commit. Os avisos gh not available no log significam o contrário: o vault é mantido, mas nunca sai do servidor. Portanto, um VPS avariado leva a sua memória consigo.

Mantenha também uma cópia sob o seu controlo.

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

Copie esse ficheiro para fora do servidor com scp e depois elimine-o do servidor. Para ler a memória no Obsidian, aponte o Obsidian para um clone do repositório do vault. Os Wikilinks e backlinks funcionam normalmente, tal como a vista de grafo. É seguro editar manualmente os cartões e CORE.md. Não altere MOC.md e .graph/, porque a execução noturna regenera ambos.

Trate o cofre como um registo da sua vida

Esse diretório é um registo datado do que disse, de quem conheceu e do que decidiu, numa máquina que aluga. Isto tem duas consequências.

A auto-hospedagem desloca o armazenamento, não o processamento. Cada interação é enviada para o seu fornecedor de modelos, e cada nota de voz é enviada para o Deepgram. O cofre é seu. Os pedidos não são privados para as empresas que os processam. Executar você mesmo a camada de memória, como num servidor de memória Mem0 no seu próprio VPS, segue o mesmo modelo: o armazenamento é local, mas a chamada ao modelo continua a sair do servidor. Se um assunto for demasiado sensível para ser enviado a terceiros, mantenha-o fora do chat.

O alcance dessa conta abrange todo o cofre. As ferramentas do Iva são executadas diretamente no host através de Node's fs e child_process, sem Docker nem sandbox, por isso uma interação comprometida tem o acesso que o utilizador do serviço tiver. É por isso que a conta não mantém nenhum sudo depois da instalação e que a lista de permissões merece mais atenção do que parece: é ela que decide quais mensagens se transformam em comandos no servidor. Se quiser ter o assistente consigo sem abrir nada, este é o mesmo padrão usado para aceder a um agente Hermes auto-hospedado a partir do telemóvel, com o cliente de chat a desempenhar a função que, de outro modo, caberia a um endpoint público.

O que falha e a mensagem apresentada

Build terminated, exit 137. O killer de falta de memória do kernel terminou o build. O instalador adiciona swap apenas quando a RAM é inferior a 1.5 GB e não existe swap, por isso adicione-a manualmente e execute novamente o instalador.

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

Failed to connect to bus. Cada comando systemctl --user apresenta esta mensagem quando a shell não tem um bus de sessão do utilizador, que é fornecido por sudo -iu iva. Abra uma sessão SSH normal como esse utilizador ou exporte XDG_RUNTIME_DIR=/run/user/$(id -u iva) antes de executar o comando.

O bot ignora os seus comandos. TELEGRAM_ALLOWED_USER_IDS está vazio e a allowlist rejeita por predefinição. Envie uma mensagem ao bot: ele responde com o seu ID numérico e nada mais. Coloque esse ID em .env e execute iva restart.

O bot fica silencioso imediatamente depois de iva config. O wizard pode mover IVA_PORT sem atualizar ASSISTANT_HOST, fazendo com que a bridge se ligue a uma porta onde nada responde. Compare as duas linhas e reinicie.

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

Uma mensagem de voz não recebe resposta. A Bot API do Telegram recusa transferências de ficheiros superiores a 20 MB, por isso a bridge nunca recebe áudios longos e não tem nada para enviar ao Deepgram. Divida o ficheiro antes de o enviar.

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

Um turno fica bloqueado e nunca responde. O estado bloqueado do workflow persiste depois de um reinício e volta a ser colocado na fila, por isso reiniciar sozinho não o elimina. iva reset coloca esse estado em quarentena e reinicia ambos os serviços. /new no chat inicia uma conversa nova.

O Chromium falha no Ubuntu 24.04. O Ubuntu 24.04 bloqueia user namespaces não privilegiados através do AppArmor, por isso a sandbox do próprio Chromium não consegue iniciar e agent-browser falha. O instalador contorna o problema escrevendo "--no-sandbox" em ~/.agent-browser/config.json. Tenha em conta que esta configuração existe. Reduz o isolamento do browser, o que constitui mais uma razão para a conta não ser proprietária de nada além do Iva.

FAQ

Preciso de um domínio ou de uma porta aberta para alojar o Iva?

Não. O Iva comunica com o Telegram através de long polling: iva-telegram-poll.service chama getUpdates e fica à espera, pelo que todas as ligações são de saída do servidor. Nada precisa de conseguir chegar ao servidor a partir do exterior, por isso não precisa de um registo DNS nem de um certificado. A porta HTTP do próprio agente, 8723, está associada a 127.0.0.1, e a documentação do projeto indica que não deve expô-la. Uma firewall que permita SSH e mais nada é a configuração correta.

Quanto custa executar o Iva por mês?

Com os preços de tabela publicados em agosto de 2026, um VPS pequeno a 5 dólares, mais o plano de modelo com preço fixo mais baixo, a 5 dólares, totaliza cerca de 10 dólares americanos por mês. O Ollama Cloud custa 20 dólares em alternativa e cobra os modelos de fronteira à parte. Os créditos iniciais do Deepgram cobrem a utilização de voz no início, e os níveis de pesquisa na Web incluem utilizações gratuitas. O OpenRouter funciona num modelo de pagamento conforme a utilização, por isso não tem um valor mensal fixo.

Onde é que o Iva guarda os meus dados e como faço uma cópia de segurança?

Por predefinição, em ~/iva/vault, definido por ASSISTANT_VAULT_DIR. É um repositório git privado separado, constituído por ficheiros markdown simples: CORE.md, daily/YYYY-MM-DD.md, cards/ e summaries/. O memory doctor das 05:00 faz commit e push do repositório. Isso só é útil se o repositório tiver um remote, por isso execute gh auth login ou adicione o seu próprio remote durante a configuração. Mantenha também uma cópia offline com tar czf ~/iva-vault-backup.tgz -C ~/iva vault e transfira esse ficheiro para fora do servidor.

Os meus dados são privados se eu alojar o Iva?

O armazenamento é seu. O processamento não é. O vault permanece no seu disco até fazer push dele, e .env tem o modo 0600 e pertence ao utilizador do serviço. As chamadas aos modelos e a transcrição de voz usam APIs na cloud, por isso essas mensagens passam pelo seu fornecedor de modelos e pelo Deepgram. O Iva é licenciado ao abrigo da licença MIT, pelo que pode consultar exatamente o que envia e alterá-lo. A allowlist do Telegram funciona com negação por predefinição, o que significa que um TELEGRAM_ALLOWED_USER_IDS vazio bloqueia todos, incluindo você.

Que fornecedores de modelos são compatíveis com o Iva?

MODEL_PROVIDER aceita opencode (OpenCode Go), ollama (Ollama Cloud), openrouter e codex. O OpenRouter usa um identificador de fornecedor, como anthropic/claude-sonnet-4.5, e disponibiliza a maior seleção de modelos. codex inicia sessão numa subscrição ChatGPT existente com iva login e não usa uma chave de API. Defina o fornecedor e a janela de contexto correspondente para o tamanho real do modelo. Em seguida, execute iva restart, porque o modelo só é lido no arranque do processo.