Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
---
id: installation
title: Installation
slug: /
---
Mercury offers standalone releases for specific desktop and server targets, plus an npm package requiring Node.js 22 or newer. Android uses the npm route through Termux.
## The easiest way: Mercury Desktop
On a Mac, Windows or Linux computer, [download Mercury Desktop](/download). It installs Mercury for you, with no terminal, and keeps it updated. It can also connect to a Mercury on another machine. See [Install & first run](/docs/desktop/mercury-desktop).
The rest of this page installs the Mercury runtime from the command line: for servers, headless machines, Termux, or if you prefer the terminal.
## Pick your platform
- **[macOS](/docs/getting-started/platforms/macos)** — `curl | sh` installer, Homebrew-style PATH setup, Apple Silicon & Intel binaries.
- **[Linux](/docs/getting-started/platforms/linux)** — standalone x64/arm64 binaries for glibc-based systems.
- **[Windows](/docs/getting-started/platforms/windows)** — PowerShell installer, native `.exe`, optional WSL path.
- **[Termux & lightweight devices](/docs/getting-started/platforms/termux)** — Android (Termux), iSH, Alpine containers, Raspberry Pi.
- **[Cloud Instance](/docs/getting-started/platforms/cloud-instance)** — hosted Mercury Code via [Atomic Bot](https://atomicbot.ai/?utm_source=agent). No install needed.
## Two install paths
Choose a route supported by your operating system and CPU.
### 1. Standalone binary (no Node.js required)
A one-line installer downloads the latest pre-built binary, verifies its SHA-256, and puts it on your `PATH`.
```bash
# macOS / Linux
curl -fsSL https://mercuryagent.sh/install.sh | sh
```
```powershell
# Windows
irm https://mercuryagent.sh/install.ps1 | iex
```
The installer:
- Detects your OS and CPU architecture (macOS arm64/x64, Linux x64/arm64, Windows x64).
- Resolves the latest GitHub release.
- Verifies the SHA-256 checksum against `checksums.txt` and tests the staged binary with `--version` before replacing an existing installation.
- Installs to `~/.mercury/bin/mercury` (or `%USERPROFILE%\.mercury\bin\mercury.exe`) and updates your shell `PATH`.
#### Standalone support limits
| System | Published runtime targets | Other environments |
|---|---|---|
| macOS | arm64, x64 | No 32-bit binary |
| Linux | glibc-based x64, arm64 | No musl/Alpine, Android/bionic, or 32-bit binary |
| Windows | x64, including an older-CPU baseline build | No native Windows arm64 or 32-bit binary |
Linux x64 also has a baseline build for CPUs without AVX2. The installer can select or fall back to it, but the binary still needs a compatible operating system and libc. A baseline build does not add support for every CPU or distribution.
For Alpine, Termux, Windows on ARM, or another target without a published binary, consider the [npm route](#2-npm-package-requires-nodejs-22) if a compatible Node.js 22+ build and the package's dependencies are available. The npm package is not a guarantee of support on every machine. See the platform guides for requirements.
#### Failed installer updates
The command-line installers check the downloaded binary and dashboard before replacing existing files, including a baseline fallback when needed. If a handled file-promotion failure occurs, they attempt to restore both previous artifacts. If restoration fails, the error reports a recovery directory containing the remaining backups; preserve it until recovery is complete.
These steps are not an atomic transaction across the binary and dashboard. Power loss, forced termination, filesystem failures, and concurrent installers can interrupt recovery. Keep an independent backup for installations you rely on. This behavior applies to the standalone command-line installers; npm and Desktop updates have their own update paths.
#### Environment variables
| Variable | Default | Purpose |
|---|---|---|
| `MERCURY_VERSION` | latest | Pin to a specific version, e.g. `MERCURY_VERSION=1.1.9` |
| `MERCURY_INSTALL` | `$HOME/.mercury` | Install prefix (binary lands at `$MERCURY_INSTALL/bin/mercury`) |
| `MERCURY_NO_PATH` | _(unset)_ | Set to `1` to skip modifying your shell rc / user PATH |
### 2. npm package (requires Node.js 22+)
If you already have Node.js, the npm route is the simplest:
```bash
npm i -g @cosmicstack/mercury-agent
```
Other package managers:
```bash
bun add -g @cosmicstack/mercury-agent
pnpm add -g @cosmicstack/mercury-agent
yarn global add @cosmicstack/mercury-agent
```
Or run without installing:
```bash
npx @cosmicstack/mercury-agent
```
## Upgrade
Mercury includes a built-in upgrade command for npm installs:
```bash
mercury upgrade
```
It stops the daemon if running, removes the old package to avoid `ENOTEMPTY`, installs the latest version, and reports the version diff.
:::tip[Binary installs]
`mercury upgrade` is npm-aware. If you installed via the shell installer, re-run it to get the latest binary:
```bash
curl -fsSL https://mercuryagent.sh/install.sh | sh
```
:::
## Enable the web dashboard
After installation, run the doctor or edit your config:
```bash
mercury doctor
```
```yaml
# ~/.mercury/mercury.yaml
web:
enabled: true
```
The dashboard will be available at `http://127.0.0.1:6174` when Mercury is running.