Self-host Iva: a Telegram AI assistant
Run Iva, a self hosted Telegram AI assistant, on a small VPS: no open ports, no domain, systemd user services and an Obsidian vault you back up.
What you are building
Iva is a self-hosted Telegram AI assistant, and it is one of the few you can deploy with no inbound port to open and no domain to point at it. There is no certificate either, because nothing on the box listens for the public. The service dials out to Telegram, holds the connection open, and reads your messages from the reply. Everything else follows from that one outbound connection.
Iva is MIT licensed and written in Node. Its memory is a folder of plain markdown files that Obsidian opens directly, so the notes it keeps about you stay readable without the app. This guide pins release v0.3.13, published on 6 August 2026. The repository has since been renamed from smixs/iva to smixs/iva-agent, and the commands below use the new name.
Most self-hosted software starts with a DNS (domain name system) record and a Let's Encrypt certificate issued with Certbot. Iva skips that layer completely, which is why a small VPS behind a firewall that allows only SSH is a complete deployment.
Why Iva needs no open ports
iva-telegram-poll.service is a long polling bridge. It calls Telegram's getUpdates API and waits for the answer, so every connection starts from your server. Telegram never connects back, which means there is no reverse proxy to configure and no certificate renewal to forget about.
The agent itself does listen, on 127.0.0.1 port 8723 only. The project documentation is direct about it: do not expose port 8723, and any reverse proxy you put in front of it must keep the bearer token requirement. Check the bind address after the install.
sudo ss -tlnp | grep 8723The address must read 127.0.0.1:8723. A wildcard address such as 0.0.0.0:8723 means the agent's HTTP routes are reachable from the internet, and you should fix that before you send the bot anything private.
So the firewall stays shut. Allow SSH before you enable it, because ufw enable with no SSH rule risks cutting off SSH access.
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw statusWhat the one line installer actually does
The project's front page gives you one command that pipes a script from GitHub into bash. Read the script first, because it does much more than install one program.
curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh -o iva-install.sh
less iva-install.sh- It installs system packages with the detected package manager:
git,gh,python3,ffmpeg,pandocandpoppler-utils. - It attempts to create a 2 GB swapfile at
/swapfile, or enable an existing one, when RAM is under 1500 MB and total swap is under 1024 MB. - It installs nvm, then Node 24, which is the minimum version Iva runs on.
- It installs
uv, the Python package manager, into~/.local/bin. - It clones the repository to
~/ivaand runsnpm ci. - It installs
agent-browseras a global npm package, which then downloads Chromium, and installs the Google Workspace CLI,gws, as a global npm package without sudo. - It runs the setup wizard, builds the project, and creates the vault.
- It writes an
ivacommand into~/.local/binand installs the systemd user units.
That is a lot of software for one line. It also explains the README's instruction to install as an ordinary user and not as root: the agent's shell tool later runs with the privileges the installer had. The script calls sudo only for the package installs and the swapfile, plus possibly once more for the Chromium step, through one helper that runs commands directly when you are already root.
Create a dedicated user before you install
Give Iva its own account. The agent runs shell commands on the host through Node's child_process, with no container and no sandbox, so the account it runs under is the security boundary.
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 ivaenable-linger matters because Iva runs as systemd user units. Without linger, systemd normally stops that user's services after their last session ends, so the assistant would die when you close SSH. The same rule governs any service and timer you write yourself under systemd.
The account needs sudo only while the installer adds packages. Take it away when the install is finished.
sudo deluser iva sudoLog in as that user directly over SSH. A shell you enter with sudo -iu iva has neither DBUS_SESSION_BUS_ADDRESS nor XDG_RUNTIME_DIR set, so every systemctl --user command fails with Failed to connect to bus. Drawing this boundary is the same exercise as running services under least privilege users.
Install a pinned release instead of piping to bash
The installer has a useful property. Before it clones anything, it checks whether the directory the script sits in already holds a package.json containing "eve". If it does, it builds that checkout and skips the clone. So you can choose the version yourself.
git clone --branch v0.3.13 https://github.com/smixs/iva-agent.git ~/iva
cd ~/iva
git log -1 --oneline
bash install.shNow you know which code is running. You do not know that when the script clones main at whatever state it happens to be in that hour. Iva shipped five releases between 4 and 6 August 2026, so main this morning and main this afternoon are not the same program.
A tag checkout leaves git in a detached HEAD state. That runs fine, but understand the limit: iva update moves the checkout forward onto the update branch, so the pin is a known starting point and not a permanent freeze. iva version prints the package version and the git commit, so you can always see where you are.
To move to a later release on purpose, list the tags, check out the one you picked in place of v0.3.13 below, then run the installer from inside the checkout again. For a fresh installation, the installer also accepts a release tag through BRANCH: it runs git clone --branch "$BRANCH" "$REPO_URL" "$INSTALL_DIR", and Git's --branch accepts tags. Its environment variables include REPO_URL, BRANCH and INSTALL_DIR; checking out the tag yourself is another way to pin it.
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 stops the wizard from running again over a .env that already works. Run iva version afterwards to confirm the commit you landed on.
The five wizard steps, and the keys they ask for
- Model provider and model.
MODEL_PROVIDERacceptsopencode,ollama,openrouterorcodex. The wizard validates the selected model live. OpenCode, Ollama and Codex fetch model lists; OpenRouter takes a slug you enter and tests it with a tool call. - Voice and search. A Deepgram key transcribes voice notes. A web search key (Tavily, Exa, Parallel or Brave) is optional.
- Telegram bot token from @BotFather, checked against the
getMeendpoint. - Access control. You send your bot a message, and the wizard reads your numeric user ID out of
getUpdates. - System settings. IANA timezone, vault directory, and the local port, 8723 by default.
OpenCode Go now requires the client's own User-Agent and a stable x-opencode-session header. Iva added those headers in v0.4.1, so use a release with that fix for Go rather than the pinned v0.3.13. Go's current policy also calls for typical coding agent traffic.
Two of those are dependencies the "one command" framing hides. Iva ships no model, so it needs a model API key or an existing ChatGPT subscription before it answers anything; OpenRouter's free models do not require a model subscription. It also does not transcribe audio itself, so voice notes need a separate service. Deepgram's nova-3 model with DEEPGRAM_LANGUAGE=multi detects the language, and new Deepgram accounts get starter credits that cover months of personal use. Text works with the model key alone. Only voice depends on Deepgram.
Check what the wizard wrote.
grep -E '^(MODEL_PROVIDER|TELEGRAM_ALLOWED_USER_IDS|ASSISTANT_VAULT_DIR|IVA_PORT)=' ~/iva/.env
ls -l ~/iva/.envls should print -rw-------, mode 0600, because that file holds every key you just pasted. TELEGRAM_ALLOWED_USER_IDS must hold your numeric ID. The allowlist is fail closed, so an empty value means Iva answers nobody.
The model is read once, at process start. Editing MODEL_PROVIDER or a model name in .env changes nothing until you run iva restart. On openrouter the model name is a vendor slug such as anthropic/claude-sonnet-4.5, not a bare name. On codex there is no API key at all: iva login signs in to an existing ChatGPT subscription.
What does Iva cost to run each month
The data behind this chart
[
{
"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
}
]The model list prices were checked on 5 November 2026; the VPS line is a monthly budget, not a quoted hosting plan. A small VPS budget of 5 US dollars plus the OpenCode Go plan at 10 dollars comes to about 15 dollars a month, with the Go compatibility requirement above. OpenCode's own Go page lists that monthly price with no first month discount. Ollama Cloud is the other subscription option at 20 dollars for its Pro plan, and usage beyond the plan's included credits is billed on top. Voice costs 0 while the Deepgram starter credits last.
OpenRouter's :free models require no credit purchase, so a tool-capable free text model brings the example total down to 5 dollars a month for the VPS alone. Free models have usage limits; Iva's separate OpenRouter vision calls and optional paid features can add costs. OpenRouter's paid models are pay as you go, so your bill tracks your usage. That is the option to watch: an assistant with a long conversation history can outspend a subscription quickly. Set the context window variable to the model's real size, since an inflated value delays compaction and risks overflowing the model's window.
The two services and the two timers
iva.serviceruns the agent itself.iva-telegram-poll.serviceruns the long polling bridge that talks to Telegram.iva-memory-doctor.timerfires at 05:00 and runs the nightly maintenance pass over the vault.iva-update-check.timerfires at 10:00 and checks whether a newer release exists.iva-telegram-userbot.serviceexists only if you set up the optional Telethon proxy.
iva status
systemctl --user status iva.service iva-telegram-poll.service
systemctl --user list-timers
iva logs polliva status reports both services and both watchdog timers. systemctl --user list-timers prints the next run time for each timer, which is how you confirm the memory doctor will actually run tonight. Both services should sit in active (running). If one restarts in a loop, journalctl --user -u iva.service -n 100 gives the reason.
The split matters when you debug. The bridge can be alive and polling while the agent is down, and then Telegram accepts your message and nothing ever answers it. iva logs poll follows the bridge, iva logs follows the agent, so the two logs tell you which half is broken.
Where the Obsidian vault lives, and how to back it up
ASSISTANT_VAULT_DIR defaults to vault inside the install directory, so the memory sits at ~/iva/vault. It is its own git repository, separate from the code, which is what lets you update Iva without touching your notes.
vault/CORE.mdholds durable facts and standing preferences, capped at 1200 characters, and travels in every system prompt.vault/daily/YYYY-MM-DD.mdis the day's transcript, treated as append only.vault/cards/holds typed cards for contacts, projects, decisions, ideas and notes.vault/summaries/daily/,weekly/,monthly/andyearly/hold the rollups.vault/attachments/holds files by date, andvault/.graph/holds the link graph.vault/schema.jsondefines the card types and the decay rules.
Rollups run on a schedule inside the process. The daily pass at 04:00 turns yesterday's transcript into cards and a summary and rewrites CORE.md, then the weekly, monthly and yearly passes compress those in turn. At 05:00 the memory doctor runs a deterministic pass with no model involved: it enforces the schema, rebuilds the link graph, regenerates the index, then commits and pushes.
That push is your backup, and it is the step people miss. If the vault has no git remote, the doctor tries to create a private GitHub repository through gh, which needs an authenticated GitHub CLI.
gh auth login
systemctl --user start iva-memory-doctor.service
cd ~/iva/vault && git log --oneline -3A commit dated today confirms a local commit; check the doctor's log for doctor: done, vault committed and pushed to confirm the backup left the server. doctor: no remote and gh unavailable means the push was skipped, so a dead VPS takes your memory with it unless you have another backup.
Keep a copy you control as well.
tar czf ~/iva-vault-backup.tgz -C ~/iva vaultCopy that file off the box with scp, then delete it from the server. To read the memory in Obsidian, point Obsidian at a clone of the vault repository. Wikilinks and backlinks work as they are, and so does the graph view. Editing cards and CORE.md by hand is safe. Leave MOC.md and .graph/ alone, because the nightly pass regenerates both.
Treat the vault as a log of your life
That directory is a dated record of what you said, who you met and what you decided, on a machine you rent. Two things follow from it.
Self-hosting moves the storage, not the processing. Every turn goes to your model provider, and every voice note goes to Deepgram. The vault is yours. The requests are not private from the companies serving them. Running the memory layer yourself, as with a Mem0 memory server on your own VPS, has the same shape: the store is local while the model call still leaves the building. If a subject is too sensitive for a third party, keep it out of the chat.
The reach of that account is the whole vault. Iva's tools run host native through Node's fs and child_process, with no Docker and no sandbox, so a hijacked turn has whatever access the service user has. That is why the account holds no sudo after the install, and why the allowlist deserves more attention than it looks: it is the gate that decides whose messages become commands on your server. If you want the assistant in your pocket without opening anything, this is the same pattern used to reach a self-hosted Hermes agent from your phone, with the chat client doing the job a public endpoint would otherwise do.
What breaks, and the message you will see
Build killed, exit 137. Exit 137 indicates termination by SIGKILL, calculated as 128 plus signal 9; it does not establish that the kernel's out of memory killer took the build. A manually sent SIGKILL produces the same result. Check sudo journalctl -k -b for an OOM report before treating this as a memory problem. The installer attempts to add or enable swap when RAM is under 1500 MB and total swap is under 1024 MB, including when some swap already exists. If the logs confirm an OOM kill, check existing swap before adding more; use the commands below only if /swapfile does not already exist, then run the installer again.
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
free -hFailed to connect to bus. Every systemctl --user command prints this when the shell has no user session bus, which is what sudo -iu iva gives you. Open a normal SSH session as that user, or export XDG_RUNTIME_DIR=/run/user/$(id -u iva) before the command.
The bot ignores you. TELEGRAM_ALLOWED_USER_IDS is empty, and the allowlist is fail closed. With an empty allowlist, a direct message gets a reply saying the bot is not configured yet. Run iva config and send the bot a message so the wizard discovers your numeric ID, then run iva restart.
The bot goes silent right after iva config. Before v0.1.4, the wizard could move IVA_PORT without updating ASSISTANT_HOST, so the bridge connected to a port where nothing answered. The pinned release synchronizes local addresses; compare the two lines if you have an older or manually edited configuration, then restart.
grep -E '^(IVA_PORT|ASSISTANT_HOST)=' ~/iva/.env
iva restartA voice note gets no reply. Telegram's Bot API refuses file downloads over 20 MB, so the bridge never receives long audio and has nothing to send Deepgram. Split the file before you send it.
ffmpeg -i long.ogg -f segment -segment_time 600 -c copy part-%02d.oggA turn hangs and never answers. Wedged workflow state survives a restart and re-queues itself, so restarting alone does not clear it. iva reset quarantines that state and restarts both services. /new in the chat starts a fresh conversation.
Chromium fails on Ubuntu 24.04. Ubuntu 24.04 restricts privileges inside unprivileged user namespaces through AppArmor, so Chromium's sandbox needs an appropriate AppArmor profile to start. The installer works around it by writing "--no-sandbox" into ~/.agent-browser/config.json. Know that this is there. It lowers the browser's isolation, which is one more reason the account should own nothing except Iva.
FAQ
Do I need a domain or an open port to self-host Iva?
No. Iva talks to Telegram by long polling: iva-telegram-poll.service calls getUpdates and waits, so every connection is outbound from your server. Nothing has to reach the box from outside, so you need no DNS record and no certificate. The agent's own HTTP port, 8723, binds to 127.0.0.1, and the project documentation tells you not to expose it. A firewall that allows SSH and nothing else is the correct configuration.
What does it cost to run Iva each month?
At model list prices checked on 5 November 2026, a small VPS budget of 5 dollars plus OpenCode Go at 10 dollars comes to about 15 US dollars a month; Go requires Iva's client-header fix added in v0.4.1. Ollama Cloud's Pro plan costs 20 dollars instead, and bills usage beyond its included credits on top. Deepgram starter credits cover voice at first, and Tavily has a free allowance. OpenRouter offers both paid models and free models: a tool-capable :free text model needs no credit purchase, bringing the example total to 5 dollars for the VPS, subject to usage limits and any paid vision or optional features.
Where does Iva keep my data, and how do I back it up?
In ~/iva/vault by default, set by ASSISTANT_VAULT_DIR. It is a separate private git repository of plain markdown: CORE.md, daily/YYYY-MM-DD.md, cards/ and summaries/. The 05:00 memory doctor commits and pushes it, which only helps if the repository has a remote, so run gh auth login or add a remote of your own during setup. Keep an offline copy as well with tar czf ~/iva-vault-backup.tgz -C ~/iva vault and move that file off the server.
Is my data private if I self-host Iva?
The storage is yours. The processing is not. The vault stays on your disk until you push it, and .env sits at mode 0600 owned by the service user. Model calls and voice transcription are cloud APIs, so those messages transit your model provider and Deepgram. Iva is MIT licensed, so you can read exactly what it sends and change it. The Telegram allowlist is fail closed, which means an empty TELEGRAM_ALLOWED_USER_IDS blocks everyone, including you.
Which model providers does Iva support?
In the pinned v0.3.13 release, MODEL_PROVIDER accepts opencode (OpenCode Go), ollama (Ollama Cloud), openrouter and codex. OpenCode Go now requires client headers added in Iva v0.4.1, so use a release with that fix for Go. OpenRouter takes a vendor slug such as anthropic/claude-sonnet-4.5 and offers the widest choice of models. codex signs in to an existing ChatGPT subscription with iva login and uses no API key. Later releases add more routes, including a Claude subscription and a custom OpenAI compatible endpoint. Set the provider, set the matching context window to the model's real size, then run iva restart, because the model is read once at process start.