Installation

Install your personal agent for Bittensor on your own machine.

Platform Support

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

Quick Install

Install the shared engine first. The tested Linux desktop and VS Code packages are available on the download page. Native macOS and Windows desktop packages are not published yet; use the CLI and editor workflows on those systems.

Linux / macOS / WSL2 / Android (Termux)

curl -fsSL https://minerva.maltobi.duckdns.org/install.sh | bash

Windows (native)

Run in powershell:

iex (irm https://minerva.maltobi.duckdns.org/install.ps1)

To add the desktop companion, download the published package for your platform from the download page, then choose the installed engine in Connection.

What the Installer Does

The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), downloading and verifying the latest release archive, virtual environment, global minerva command setup, and LLM provider configuration. By the end, you're ready to chat.

Installing a Specific Version

To install a particular published release instead of the latest, pass its version:

curl -fsSL https://minerva.maltobi.duckdns.org/install.sh | bash -s -- --version 0.23.1

& ([scriptblock]::Create((irm https://minerva.maltobi.duckdns.org/install.ps1))) -Version 0.23.1

Every release keeps its own directory on the release channel (https://minerva.maltobi.duckdns.org/releases/v0.23.1/) with its archives and a latest.json manifest; the installer downloads that release's archive and refuses it unless its SHA-256 matches that manifest. A version that was never published stops with Minerva v… is not published on the release channel. --version implies the release source, so it can't be combined with --source git, --branch or --commit (-Source git, -Branch, -Commit or -Tag on Windows). The version is only where the install starts: minerva update later moves it to the newest release.

Install Layout

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

Installer	Code lives at	`minerva` binary	Data directory
Per-user (default installer)	`~/.minerva/minerva-agent/`	`~/.local/bin/minerva` (symlink)	`~/.minerva/`
Root-mode (`sudo curl … \| sudo bash`)	`/usr/local/lib/minerva-agent/`	`/usr/local/bin/minerva`	`/root/.minerva/` (or `$MINERVA_HOME`)

The root-mode FHS layout (/usr/local/lib/…, /usr/local/bin/minerva) 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 ~/.minerva/ or explicit MINERVA_HOME.

After Installation

Reload your shell and start chatting:

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

To reconfigure individual settings later, use the dedicated commands:

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

Already running Minerva on another machine?

You don't need to rebuild your setup from scratch. Restore a full backup with minerva import (see Exporting Minerva to another machine), or bring over a single agent with minerva 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 — minerva backup vs minerva 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 v26 (for browser automation; existing system Node 22.22+, 24.11+, or 26+ is used as-is)
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 Minerva as a dedicated unprivileged user (e.g. a minerva 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):

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.)
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://minerva.maltobi.duckdns.org/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://minerva.maltobi.duckdns.org/install.sh | bash -s -- --skip-browser
```
The installer does not fetch cua-driver by default — upstream's installer downloads and runs a second script from a host we don't control, which isn't worth doing for a tool you may never turn on. Pass --with-computer-use to pre-install it; otherwise it installs on demand the first time you enable the Computer Use toolset.
Make minerva available to the service user's shells. The installer writes the launcher to ~/.local/bin/minerva. 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/minerva/.minerva/minerva-agent/venv/bin/minerva /usr/local/bin/minerva
```
Verify: minerva doctor should now run cleanly. If you get ModuleNotFoundError: No module named 'dotenv', you're invoking the repo source minerva file (~/.minerva/minerva-agent/minerva) with system Python instead of the venv launcher (~/.minerva/minerva-agent/venv/bin/minerva) — fix step 3.
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

Problem	Solution
`minerva: command not found`	Reload your shell (`source ~/.bashrc`) or check PATH
`API key not set`	Run `minerva model` to configure your provider, or `minerva config set OPENROUTER_API_KEY your_key`
Missing config after update	Run `minerva config check` then `minerva config migrate`

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

Symlinked home directories and external storage

Minerva supports a symlinked MINERVA_HOME and symlinked home subdirectories, including hooks, skills, sessions, and logs. During home initialization, existing directory links are preserved, and permissions on linked directories (and descendants such as logs/curator) are left to their owner.

If a link target is missing, inaccessible, or not a directory, initialization stops with a storage error naming the path and link target. Minerva does not replace the link or create its missing target: doing so could write data onto the local disk while an external or NAS volume is unmounted. Check the reported link, restore the mount or correct its target, and verify access permissions before retrying. For a deliberately new dotfiles target, create it yourself only after confirming the intended storage is available.

minerva doctor reports these failures as storage problems, not invalid YAML. Keep your existing config.yaml; running minerva setup is not the repair for an unavailable directory. This is a directory-availability check, not a mount monitor: an existing directory cannot establish that the intended volume is mounted.

Install method auto-detection

Minerva auto-detects whether it was installed from a release archive, a git checkout, Docker, or Nix, and minerva update prints the matching update command for that path. There's no env var to set — the installer writes an .install_method stamp (release, or git for --source git installs) next to the code, the Docker image bakes in a docker stamp, and Nix installs are recognized by their store path. minerva doctor also surfaces the detected method under its environment summary.

Quick Install​

Linux / macOS / WSL2 / Android (Termux)​

Windows (native)​

What the Installer Does​

Installing a Specific Version​

Install Layout​

After Installation​

Prerequisites​

Manual / Developer Installation​

Non-Sudo / System Service User Installs​

Troubleshooting​

Symlinked home directories and external storage​

Install method auto-detection​