SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-11-06

Como instalar o Iva no Telegram sem abrir portas

Aprenda a rodar o Iva v0.3.13 em um VPS usando systemd user services. Sem dominios ou certificados, apenas conexoes de saida seguras e um vault Obsidian para seus dados.

O que você vai construir

Iva é um assistente de IA para Telegram autoalojado. É uma das poucas opções que pode implementar sem abrir uma porta de entrada e sem associar um domínio ao serviço. Também não é necessário um certificado, porque nada no servidor aceita ligações públicas. O serviço estabelece a ligação de saída para o Telegram, mantém essa ligação aberta e lê as suas mensagens através da resposta. Tudo o resto resulta dessa única ligação de saída.

Iva é licenciado sob a licença MIT e foi escrito em Node. A memória consiste numa pasta de ficheiros Markdown simples que o Obsidian abre diretamente. Assim, as notas que guarda sobre si continuam legíveis sem a aplicação. Este guia fixa a release v0.3.13, publicada em 6 August 2026. O repositório foi entretanto renomeado de smixs/iva para smixs/iva-agent, e os comandos abaixo usam o novo nome.

A maioria dos softwares autoalojados começa com um registo DNS (domain name system) e um certificado Let's Encrypt emitido com o Certbot. Iva ignora completamente essa camada. Por isso, um VPS pequeno atrás de uma firewall que permita apenas SSH é suficiente para uma implementação.

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 estabelece a ligação de volta. Por isso, não é necessário configurar um reverse proxy nem lembrar-se de renovar certificados.

O próprio agente fica à escuta, mas apenas na porta 127.0.0.1 8723. A documentação do projeto é clara: não exponha a porta 8723 e, se colocar um reverse proxy à frente do agente, mantenha a exigência do bearer token. Verifique o endereço de bind depois da instalação.

sudo ss -tlnp | grep 8723

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

Assim, a firewall permanece fechada. Permita o SSH antes de ativá-la, porque ufw enable sem uma regra para SSH pode interromper o acesso por SSH.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

O que o instalador de uma linha realmente faz

A página inicial do projeto fornece um comando que envia um script do GitHub diretamente para o bash. Leia o script primeiro, pois ele faz muito mais do que instalar apenas um programa.

curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh -o iva-install.sh
less iva-install.sh
  • Ele instala pacotes do sistema usando o gerenciador de pacotes detectado: git, gh, python3, ffmpeg, pandoc e poppler-utils.
  • Ele tenta criar um swapfile de 2 GB em /swapfile, ou ativar um existente, quando a RAM é inferior a 1500 MB e o swap total é inferior a 1024 MB.
  • Ele instala o nvm e, em seguida, o Node 24, que é a versão mínima necessária para o Iva.
  • Ele instala o uv, o gerenciador de pacotes Python, em ~/.local/bin.
  • Ele clona o repositório para ~/iva e executa o npm ci.
  • Ele instala o agent-browser como um pacote npm global, que então baixa o Chromium, e instala a CLI do Google Workspace, gws, como um pacote npm global sem sudo.
  • Ele executa o assistente de configuração, compila o projeto e cria o cofre.
  • Ele escreve um comando iva em ~/.local/bin e instala as unidades de usuário do systemd.

Isso é muito software para uma única linha. Isso também explica a instrução do README para instalar como um usuário comum e não como root: a ferramenta de shell do agente é executada posteriormente com os privilégios que o instalador possuía. O script chama o sudo apenas para as instalações de pacotes e o swapfile, além de possivelmente mais uma vez para a etapa do Chromium, através de um auxiliar que executa comandos diretamente quando você já é root.

Crie um utilizador dedicado antes de instalar

Dê à Iva a sua própria conta. O agente executa comandos shell no host através do child_process do Node, sem contentor e sem sandbox, portanto a conta sob a qual é executado é 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

O enable-linger é importante porque a Iva é executada como unidades de user do systemd. Sem o linger, o systemd normalmente para os serviços desse utilizador após o fim da sua última sessão, pelo que o assistente terminaria quando fechasse o SSH. A mesma regra rege qualquer serviço e temporizador que crie por si próprio 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 como esse utilizador diretamente via SSH. Uma shell à qual acede com sudo -iu iva não tem nem DBUS_SESSION_BUS_ADDRESS nem XDG_RUNTIME_DIR definidos, pelo que cada comando systemctl --user falha com Failed to connect to bus. Definir este limite é o mesmo exercício que executar serviços com utilizadores de privilégio mínimo.

Instale uma versão fixada em vez de usar pipe para o bash

O instalador possui uma propriedade útil. Antes de clonar qualquer coisa, ele verifica se o diretório onde o script está localizado já contém um package.json com um "eve". Se contiver, ele compila esse checkout e ignora a clonagem. Assim, você pode escolher a versão por conta própria.

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

Agora você sabe qual código está em execução. Você não tem essa garantia quando o script clona o main no estado em que ele estiver naquela hora. Iva lançou cinco versões entre 4 e 6 de agosto de 2026, portanto, o main desta manhã e o main desta tarde não são o mesmo programa.

Um checkout de tag deixa o git em um estado de HEAD desanexado (detached HEAD). Isso funciona bem, mas entenda a limitação: o iva update move o checkout para a frente na branch de atualização, portanto, a fixação é um ponto de partida conhecido e não um congelamento permanente. O iva version imprime a versão do pacote e o commit do git, para que você possa sempre ver onde está.

Para mudar para uma versão posterior de forma intencional, liste as tags, faça o checkout daquela que você escolheu no lugar de v0.3.13 abaixo e execute o instalador novamente a partir de dentro do checkout. Para uma instalação nova, o instalador também aceita uma tag de versão através da BRANCH: ele executa o git clone --branch "$BRANCH" "$REPO_URL" "$INSTALL_DIR", e o --branch do Git aceita tags. Suas variáveis de ambiente incluem REPO_URL, BRANCH e INSTALL_DIR; fazer o checkout da tag manualmente é outra forma de fixá-la.

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

O --skip-setup impede que o assistente seja executado novamente sobre um .env que já funciona. Execute o iva version depois para confirmar o commit em que você parou.

Os cinco passos do assistente e as chaves solicitadas

  1. Fornecedor de modelo e modelo. O MODEL_PROVIDER aceita opencode, ollama, openrouter ou codex. O assistente valida o modelo selecionado em tempo real. OpenCode, Ollama e Codex obtêm listas de modelos; o OpenRouter utiliza um slug que você insere e testa com uma chamada de ferramenta.
  2. Voz e pesquisa. Uma chave do Deepgram transcreve notas de voz. Uma chave de pesquisa na web (Tavily, Exa, Parallel ou Brave) é opcional.
  3. Token do bot do Telegram obtido através do @BotFather, verificado contra o endpoint getMe.
  4. Controlo de acesso. Você envia uma mensagem ao seu bot e o assistente lê o seu ID de utilizador numérico a partir do getUpdates.
  5. Definições do sistema. Fuso horário IANA, diretório do cofre (vault) e a porta local, 8723 por predefinição.

O OpenCode Go requer agora o User-Agent do próprio cliente e um cabeçalho x-opencode-session estável. A Iva adicionou esses cabeçalhos na v0.4.1, por isso utilize uma versão com essa correção para Go em vez da v0.3.13 fixada. A política atual do Go também requer tráfego típico de agente de programação.

Dois desses itens são dependências que a estrutura de "um comando" oculta. A Iva não distribui nenhum modelo, por isso necessita de uma chave de API de modelo ou de uma subscrição ChatGPT existente antes de responder a qualquer coisa; os modelos gratuitos do OpenRouter não requerem uma subscrição de modelo. Também não transcreve áudio por si própria, pelo que as notas de voz necessitam de um serviço separado. O modelo nova-3 do 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. Apenas a voz depende do Deepgram.

Verifique o que o assistente escreveu.

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

O ls deve imprimir -rw-------, modo 0600, porque esse ficheiro contém todas as chaves que acabou de colar. O TELEGRAM_ALLOWED_USER_IDS deve conter o seu ID numérico. A lista de permissões (allowlist) é bloqueada por predefinição, pelo que um valor vazio significa que a Iva não responde a ninguém.

O modelo é lido uma vez, no início do processo. Editar o MODEL_PROVIDER ou um nome de modelo no .env não altera nada até que execute o iva restart. No openrouter, o nome do modelo é um slug de fornecedor, como anthropic/claude-sonnet-4.5, e não um nome simples. No codex não existe qualquer chave de API: o iva login inicia sessão numa subscrição ChatGPT existente.

Quanto custa executar o Iva por mês

GráficoMonthly cost of a self-hosted Iva, model list prices and a VPS budget, November 2026
Os dados por trás deste gráfico
[
  {
    "plan": "Small VPS, monthly budget",
    "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": "VPS plus OpenRouter free text",
    "usd_per_month": 5
  }
]

Os preços de tabela dos modelos foram verificados em 5 de novembro de 2026; o valor do VPS é um orçamento mensal, não uma proposta de alojamento. Um orçamento de 5 dólares americanos para um VPS pequeno, mais o plano OpenCode Go de 10 dólares, totaliza cerca de 15 dólares por mês, respeitando o requisito de compatibilidade com o Go indicado acima. A própria página do Go da OpenCode apresenta esse preço mensal sem desconto no primeiro mês. O Ollama Cloud é a outra opção de subscrição, a 20 dólares pelo plano Pro, e o uso além dos créditos incluídos no plano é faturado separadamente. O custo de voz é de 0 enquanto durarem os créditos iniciais do Deepgram.

Os modelos :free da OpenRouter não exigem a compra de créditos, por isso um modelo de texto gratuito com suporte a ferramentas reduz o total do exemplo para 5 dólares por mês, considerando apenas o VPS. Os modelos gratuitos têm limites de uso; as chamadas de visão separadas do Iva através da OpenRouter e as funcionalidades pagas opcionais podem acrescentar custos. Os modelos pagos da OpenRouter são faturados conforme o uso, por isso a fatura acompanha o consumo. Esta é a opção que exige atenção: um assistente com um histórico de conversação longo pode ultrapassar rapidamente o custo de uma subscrição. Defina a variável da janela de contexto para o tamanho real do modelo, porque um valor demasiado alto atrasa a compactação e pode exceder a janela do modelo.

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 reside e como fazer o backup

ASSISTANT_VAULT_DIR usa vault como padrão dentro do diretório de instalação, portanto a memória fica em ~/iva/vault. Ele é o seu próprio repositório git, separado do código, o que permite atualizar o Iva sem tocar nas suas notas.

  • vault/CORE.md armazena fatos duráveis e preferências permanentes, limitados a 1200 caracteres, e viaja em cada prompt do sistema.
  • vault/daily/YYYY-MM-DD.md é a transcrição do dia, tratada apenas como adição.
  • vault/cards/ armazena cartões tipados para contatos, projetos, decisões, ideias e notas.
  • vault/summaries/daily/, weekly/, monthly/ e yearly/ armazenam os rollups.
  • vault/attachments/ armazena arquivos por data, e vault/.graph/ armazena o grafo de links.
  • vault/schema.json define os tipos de cartão e as regras de decaimento.

Os rollups são executados conforme um agendamento dentro do processo. A passagem diária às 04:00 transforma a transcrição de ontem em cartões e um resumo, reescreve CORE.md, e então as passagens semanal, mensal e anual comprimem esses dados sucessivamente. Às 05:00, o médico de memória executa uma passagem determinística sem envolver o modelo: ele impõe o esquema, reconstrói o grafo de links, regenera o índice e, em seguida, faz o commit e o push.

Esse push é o seu backup, e é o passo que as pessoas esquecem. Se o vault não tiver um git remote, o médico tenta criar um repositório privado no GitHub através do gh, o que requer o GitHub CLI autenticado.

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

Um commit datado de hoje confirma um commit local; verifique o log do médico em doctor: done, vault committed and pushed para confirmar que o backup saiu do servidor. doctor: no remote and gh unavailable significa que o push foi ignorado, portanto, um VPS inativo levará sua memória com ele, a menos que você tenha outro backup.

Mantenha também uma cópia sob seu controle.

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

Copie esse arquivo para fora da máquina com scp e, em seguida, apague-o do servidor. Para ler a memória no Obsidian, aponte o Obsidian para um clone do repositório do vault. Wikilinks e backlinks funcionam como estão, assim como a visualização de grafo. Editar cartões e CORE.md manualmente é seguro. Não altere MOC.md e .graph/, pois a passagem 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 killed, exit 137. O código de saída 137 indica terminação por SIGKILL, calculado como 128 mais o sinal 9; isso não confirma que o OOM killer do kernel terminou o build. Um SIGKILL enviado manualmente produz o mesmo resultado. Consulte sudo journalctl -k -b para verificar se existe um relatório de OOM antes de tratar isto como um problema de memória. O instalador tenta adicionar ou ativar swap quando a RAM é inferior a 1500 MB e o total de swap é inferior a 1024 MB, mesmo quando já existe alguma swap. Se os logs confirmarem um OOM kill, verifique a swap existente antes de adicionar mais; use os comandos abaixo apenas se /swapfile não existir e, depois, 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 é o que sudo -iu iva fornece. Abra uma sessão SSH normal com esse utilizador ou exporte XDG_RUNTIME_DIR=/run/user/$(id -u iva) antes de executar o comando.

O bot ignora as suas mensagens. TELEGRAM_ALLOWED_USER_IDS está vazio e a allowlist aplica uma política de falha fechada. Com uma allowlist vazia, uma mensagem direta recebe uma resposta a indicar que o bot ainda não está configurado. Execute iva config e envie uma mensagem ao bot para que o assistente descubra o seu ID numérico. Depois, execute iva restart.

O bot deixa de responder imediatamente depois de iva config. Antes da v0.1.4, o assistente podia alterar IVA_PORT sem atualizar ASSISTANT_HOST. Assim, a bridge ligava-se a uma porta onde não havia nenhum serviço a responder. A release fixada sincroniza os endereços locais. Compare as duas linhas se tiver uma configuração mais antiga ou editada manualmente. Depois, 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 downloads de ficheiros superiores a 20 MB. Por isso, a bridge nunca recebe o áudio longo 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

Uma interação fica bloqueada e nunca responde. O estado bloqueado do workflow sobrevive a um reinício e volta a ser colocado na fila. Por isso, reiniciar o serviço, por si só, não o limpa. 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 restringe os privilégios dentro de user namespaces não privilegiados através do AppArmor. Por isso, a sandbox do Chromium precisa de um perfil AppArmor adequado para iniciar. O instalador contorna esta restrição escrevendo "--no-sandbox" em ~/.agent-browser/config.json. Tenha em conta que esta configuração existe. Ela 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 aguarda, por isso cada ligação é de saída a partir do seu servidor. Nada precisa de alcançar o servidor a partir do exterior, portanto não precisa de um registo DNS nem de um certificado. A própria porta HTTP do agente, 8723, fica associada a 127.0.0.1, e a documentação do projeto indica que não deve expô-la. Uma firewall que permita apenas SSH é a configuração correta.

Quanto custa executar o Iva por mês?

Com os preços de tabela dos modelos verificados em 5 November 2026, um VPS pequeno no valor de 5 dólares, mais o OpenCode Go no valor de 10 dólares, totaliza cerca de 15 dólares americanos por mês; o Go requer a correção dos cabeçalhos do cliente do Iva, adicionada na v0.4.1. O plano Pro do Ollama Cloud custa 20 dólares, em alternativa, e cobra à parte a utilização que exceda os créditos incluídos. Os créditos iniciais do Deepgram cobrem a voz no início, e o Tavily oferece uma franquia gratuita. O OpenRouter disponibiliza modelos pagos e gratuitos: um modelo de texto :free com suporte para ferramentas não requer a compra de créditos, reduzindo o total do exemplo para 5 dólares relativos ao VPS, sujeito aos limites de utilização e a quaisquer funcionalidades pagas de visão ou opcionais.

Onde guarda o Iva 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, composto por markdown simples: CORE.md, daily/YYYY-MM-DD.md, cards/ e summaries/. O memory doctor das 05:00 faz commit e push desse conteúdo. Isto 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, 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 sob a MIT, portanto pode consultar exatamente o que envia e alterá-lo. A allowlist do Telegram falha de forma segura, 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?

Na versão v0.3.13 fixada, MODEL_PROVIDER aceita opencode (OpenCode Go), ollama (Ollama Cloud), openrouter e codex. O OpenCode Go requer agora cabeçalhos do cliente adicionados no Iva v0.4.1, por isso use uma versão que inclua essa correção para o Go. O OpenRouter usa um identificador de fornecedor, como anthropic/claude-sonnet-4.5, e oferece a maior variedade de modelos. O codex inicia sessão numa subscrição ChatGPT existente com iva login e não usa uma chave de API. As versões posteriores adicionam mais rotas, incluindo uma subscrição Claude e um endpoint compatível com OpenAI personalizado. Defina o fornecedor, defina a janela de contexto correspondente para o tamanho real do modelo e execute iva restart, porque o modelo é lido uma vez no arranque do processo.

Este artigo foi útil?