RUGitHubInstall

Install

Through an AI agent

Paste this into Claude Code, Codex or Claude Desktop. The agent will check your server or Mac, run the installer and help you get a reply from your bot. Instructions for the agent.

Install Iva for me, instructions: https://iva-agent.com/install.txt

On macOS, the same installer uses Homebrew and launchd. Units are named app.iva.*; plists live in ~/Library/LaunchAgents and logs in ~/Library/Logs/Iva/. Log in on the Mac screen before installing. The Mac must stay on and awake for Iva to work. A night missed while the Mac is off is skipped; after sleep, launchd runs the pending calendar job when the Mac wakes. Use iva status and iva logs -f to inspect the installation.

Everything between curl and a working bot. One command on a fresh server: the installer asks your language, walks you through five keys, and ends by messaging you from your own bot.

Requirements

Never used a server? The host sends you an address (IP), a login and a password. On Mac or Linux open Terminal, on Windows PowerShell, type ssh root@YOUR_ADDRESS, enter the password. You’re in. First thing: make yourself a normal user and switch to it — adduser iva && usermod -aG sudo iva && su - iva — and install from there. Iva’s shell tool runs with the permissions of whoever installed it, so don’t hand it root.

If the installer ends with Failed to connect to bus: No medium found, leave the su - iva shell. Enable linger and reconnect directly:

exit                          # back to the root session on the server
loginctl enable-linger iva
exit                          # back to your own computer
ssh iva@YOUR_ADDRESS

Then run the installer again.

Step 0 (optional): prepare a fresh VPS

Brand-new server, still logged in as root? One command gets it ready — run it as root, before anything else:

bash <(curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/bootstrap.sh)

It asks three things up front — a login, its password, and the timezone — then: updates the system, installs Iva’s system packages (git gh python3 ffmpeg pandoc poppler-utils), creates that user with sudo and systemd lingering already enabled, turns on a firewall that allows SSH only, starts fail2ban and unattended security upgrades, and hardens sshd last — with a reload, so the session you’re typing in is never dropped. Every step is detect-then-skip, so re-running it is safe. It ends by printing the ssh and install.sh commands to run next. Log: /var/log/iva-bootstrap.log.

No SSH key is involved: you log in as the new user with the password you just set, and hardening stops at PermitRootLogin no. Headless runs take --non-interactive with IVA_USER and IVA_PASS, plus optional IVA_PUBKEY (authorizes a key), IVA_TZ and IVA_DISABLE_PASSWORD_AUTH (key-only login — ignored without a valid key).

Install

curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bash

The first question is your language — English or Russian — before anything touches the system. Input is read from /dev/tty, so the wizard stays interactive even piped through curl. If there’s no terminal at all (Docker, CI), setup is skipped and the script prints how to run it later.

Setup wizard

Five steps. Each key comes with a direct link to where it lives, and each is validated live — a bad key is rejected on the spot, not discovered at runtime. Enter keeps the current value, so re-running the wizard (iva config) changes only what you want.

  1. Provider and model. Ollama Cloud, OpenCode Go, an OpenAI (ChatGPT) subscription, OpenRouter or your own OpenAI-compatible endpoint (comparison); the key (or the subscription sign-in) is checked, then you pick a model.
  2. Voice, search, hybrid memory. Deepgram key (free starter credit) — Enter skips it, voice notes stay untranscribed until you add the key in /menu → 🎤 Voice; recognition language multi auto-detects ru/uz/en. The same step picks a web-search provider — Tavily, Exa, Parallel or Brave; Enter skips and search stays off — and offers optional hybrid memory with an embedding key.
  3. Telegram bot. Paste the token from @BotFather; the wizard validates it via getMe and detects the bot’s username itself.
  4. Access. Send your new bot any message — “hi” works. The wizard reads getUpdates, shows who wrote, and you pick yourself. Iva answers only these IDs; an empty list means it answers nobody.
  5. Timezone, vault, port. IANA timezone so nightly jobs run on your clock, the vault directory, and the port — default 8723, probed for conflicts.

What install.sh does

Re-running the same command later is safe: over an installation that already exists the installer updates nothing itself — it hands the installation to the one updater, exactly as iva update and repair.sh do. A checkout is put back onto its release first (edits to Iva’s own code are removed, .env, data/ and the vault are not touched), a versioned installation goes straight to its own updater, and a checkout you marked with .iva-dev is refused.

Google Workspace CLI (gws) is installed and updated under ~/.local without sudo. Services prefer ~/.local/bin over older global copies. Existing binaries are left in place; Google configuration and authorization stay under the same user account.

Every stage checks whether its work is already done and skips it, so a run after a failure costs seconds instead of minutes:

StageSkipped when
System packagesthe command is already there (git, gh, python3, ffmpeg, pandoc, pdftotext)
npm cinode_modules matches package-lock.json — npm’s own record, including the pinned eve archive
agent-browserthe binary is installed and really opens a page
gwsthe binary is installed (iva update keeps it current)
Build.output carries this installer’s stamp for the current commit, local edits and .env

The wizard, the vault check, the iva command and the systemd units are cheap, so they run every time. A run that fails is undone: the copy it made of .env goes back, the build it replaced is put back, and both copies are deleted — on Ctrl-C and on a dropped SSH session too. The code is never this script’s to move.

If the undo itself cannot finish — a read-only checkout, a full disk — nothing it saved is thrown away. Whatever is still the only copy of something stays where it is, and the installer prints each one by name before it exits: the copy of .env under data/update-backups/, and the previous build under .output.iva-install-backup-*. Read those lines before running anything else. An installation unpacked from an archive instead of cloned has no commit to compare against, so it rebuilds every time; so does one with a file the build cannot read.

Only one installer runs in an installation at a time: a second one is refused by name, with the process id of the one already working. A lock left by a run that no longer exists is taken over, so a power cut cannot leave the installation unusable.

Flags and overrides

Flags pass through the pipe with bash -s --:

curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bash -s -- --skip-setup
OptionEffect
--skip-setupinstall everything, don’t run the wizard
--non-interactiveno questions at all — defaults only, wizard skipped
-h, --helpshow the built-in help and exit
REPO_URL=…install from a fork (default https://github.com/smixs/iva-agent.git)
BRANCH=…install and keep updating from this branch (default main)
INSTALL_DIR=…where the code goes (default ~/iva)

The last three are environment variables, read by the script at startup.

If the wizard didn’t run

Skipped setup, or no terminal at install time:

cd ~/iva && npm run setup

Then repeat the regular install command:

curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bash

The installer continues the first installation while autostart is still pending. It reuses completed stages, opens the wizard with your saved values as defaults, enables autostart and sends the confirmation in Telegram. On Linux it also enables linger so Iva keeps running after you leave the SSH session. Once autostart is configured, later runs use the updater.

Next steps

View original Markdown ↗