Skip to main content

Installation

Get Kova Agent up and running in under two minutes!

Platform Support

For the full platform support matrix (which OSes, distribution methods, and platform-gated features are supported), see Platform Support.

Quick Install​

To easily install the command-line and desktop applications, download the Kova Desktop installer from our website and run it.

Without Kova Desktop:​

For a command-line only install without Kova Desktop, run:

Linux / macOS / WSL2 / Android (Termux)​

curl -fsSL https://kova-agent.neuralstudio.in/install.sh | bash

Windows (native)​

Run in powershell:

iex (irm https://kova-agent.neuralstudio.in/install.ps1)

If you want to install & run Kova Desktop after a command-line only install, simply run

kova desktop

What the Installer Does​

The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global kova command setup, and LLM provider configuration. By the end, you're ready to chat.

Install Layout​

Where the installer puts things depends on whether you're installing as a normal user or as root:

InstallerCode lives atkova binaryData directory
Per-user (git installer)~/.kova/kova-agent/~/.local/bin/kova (symlink)~/.kova/
Root-mode (sudo curl … | sudo bash)/usr/local/lib/kova-agent//usr/local/bin/kova/root/.kova/ (or $KOVA_HOME)

The root-mode FHS layout (/usr/local/lib/…, /usr/local/bin/kova) matches where other system-wide developer tools land on Linux. It's useful for shared-machine deployments where one system install should serve every user. Per-user config (auth, skills, sessions) still lives under each user's ~/.kova/ or explicit KOVA_HOME.

After Installation​

Reload your shell and start chatting:

source ~/.bashrc   # or: source ~/.zshrc
kova             # Start chatting!

To reconfigure individual settings later, use the dedicated commands:

kova model          # Choose your LLM provider and model
kova tools          # Configure which tools are enabled
kova gateway setup  # Set up messaging platforms
kova config set     # Set individual config values
kova config get     # Inspect individual config values
kova setup          # Or run the full setup wizard to configure everything at once
Fastest path: Nous Portal

One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling:

kova setup --portal

That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.

Already running Kova on another machine?

You don't need to rebuild your setup from scratch. Restore a full backup with kova import (see Exporting Kova to another machine), or bring over a single agent with kova profile import (see Moving a single profile to another machine). Note that a profile export excludes credentials by design, so an export alone is not a full backup — kova backup vs kova profile export explains which to use.

Prerequisites​

Installer: On non-Windows platforms, the only prerequisite is Git. On Linux, also make sure curl and xz-utils are available (the installer downloads Node.js as a .tar.xz archive). The desktop app additionally requires g++ (or build-essential on Debian/Ubuntu) to compile native modules. The installer automatically handles everything else:

  • uv (fast Python package manager)
  • Python 3.11 (via uv, no sudo needed)
  • Node.js v22 (for browser automation and WhatsApp bridge)
  • ripgrep (fast file search)
  • ffmpeg (audio format conversion for TTS)
info

You do not need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what's missing and installs it for you. Just make sure git is available (git --version). On Linux, ensure curl and xz-utils are installed (sudo apt install curl xz-utils on Debian/Ubuntu). For the desktop app, also install build-essential (sudo apt install build-essential).

Nix users

Nix is no longer an explicitly supported install path (best-effort only). If you already use Nix (on NixOS, macOS, or Linux), there's a dedicated setup path with a Nix flake, declarative NixOS module, and optional container mode. See the Nix & NixOS Setup guide.

Manual / Developer Installation​

If you want to clone the repo and install from source — for contributing, running from a specific branch, or having full control over the virtual environment — see the Development Setup section in the Contributing guide.

Non-Sudo / System Service User Installs​

Running Kova as a dedicated unprivileged user (e.g. a kova systemd service account, or any user without sudo access) is supported. The only thing on the install path that genuinely needs root is Playwright's --with-deps step, which apt-installs shared libraries (libnss3, libxkbcommon, etc.) used by Chromium. The installer detects whether sudo is available and gracefully degrades when it isn't — it will install the Chromium binary into the service user's own Playwright cache and print the exact command an administrator needs to run separately.

Recommended split (Debian/Ubuntu):

  1. One time, as an admin user with sudo, install the system libraries Chromium needs:

    sudo npx playwright install-deps chromium

    (You can run this from anywhere — npx will fetch Playwright on the fly.)

  2. As the unprivileged service user, run the regular installer. It will detect the missing sudo, skip --with-deps, and install Chromium into the user's local Playwright cache:

    curl -fsSL https://kova-agent.neuralstudio.in/install.sh | bash

    If you want to skip the Playwright step entirely — for example because you're running headless and don't need browser automation — pass --skip-browser:

    curl -fsSL https://kova-agent.neuralstudio.in/install.sh | bash -s -- --skip-browser

    The installer also pre-installs cua-driver so the Computer Use toolset works the moment you enable it; pass --skip-computer-use to opt out (it will then install on demand when you enable the tool).

  3. Make kova available to the service user's shells. The installer writes the launcher to ~/.local/bin/kova. System service accounts often have a minimal PATH that doesn't include ~/.local/bin. Either add it to the user's environment, or symlink the launcher into a system location:

    # Option A — add to the service user's profile
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

    # Option B — symlink system-wide (run as an admin)
    sudo ln -s /home/kova/.kova/kova-agent/venv/bin/kova /usr/local/bin/kova

  4. Verify: kova doctor should now run cleanly. If you get ModuleNotFoundError: No module named 'dotenv', you're invoking the repo source kova file (~/.kova/kova-agent/kova) with system Python instead of the venv launcher (~/.kova/kova-agent/venv/bin/kova) — fix step 3.

  5. Running the messaging gateway from this account? A user-level service stops at logout and does not start at boot until you enable lingering for the service user:

    sudo loginctl enable-linger <service-user>

    See Messaging Gateway for the service setup itself.

The same pattern works on Arch (the installer uses pacman with the same sudo-detection logic), Fedora/RHEL, and openSUSE — those distros don't support --with-deps at all, so an administrator always installs the system libraries separately. The relevant dnf/zypper commands are printed by the installer.

Troubleshooting​

ProblemSolution
kova: command not foundReload your shell (source ~/.bashrc) or check PATH
API key not setRun kova model to configure your provider, or kova config set OPENROUTER_API_KEY your_key
Missing config after updateRun kova config check then kova config migrate

For more diagnostics, run kova doctor — it will tell you exactly what's missing and how to fix it.

Install method auto-detection​

Kova auto-detects whether it was installed via the git installer, Docker, or NixOS, and kova update prints the matching update command for that path. There's no env var to set — the detection is based on the install layout (~/.kova/kova-agent/ checkout, Docker image stamp, or Nix store path). kova doctor also surfaces the detected method under its environment summary.