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 8723O 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 statusO 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,pandocepoppler-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
~/ivae executa onpm ci. - Ele instala o
agent-browsercomo 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
ivaem~/.local/bine 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 ivaO 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 sudoInicie 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.shAgora 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 restartO --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
- Fornecedor de modelo e modelo. O
MODEL_PROVIDERaceitaopencode,ollama,openrouteroucodex. 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. - Voz e pesquisa. Uma chave do Deepgram transcreve notas de voz. Uma chave de pesquisa na web (Tavily, Exa, Parallel ou Brave) é opcional.
- Token do bot do Telegram obtido através do @BotFather, verificado contra o endpoint
getMe. - 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. - 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/.envO 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
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.serviceexecuta o próprio agente.iva-telegram-poll.serviceexecuta 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.serviceexiste apenas se configurar o proxy Telethon opcional.
iva status
systemctl --user status iva.service iva-telegram-poll.service
systemctl --user list-timers
iva logs polliva 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.mdarmazena 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/eyearly/armazenam os rollups.vault/attachments/armazena arquivos por data, evault/.graph/armazena o grafo de links.vault/schema.jsondefine 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 -3Um 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 vaultCopie 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 -hFailed 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 restartUma 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.oggUma 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.