Install

Nimbus installs per-user — no administrator or sudo access required on any platform. The installer places the nimbus binary on your PATH and creates a data directory. It does not configure autostart on any platform — you start the Gateway yourself with nimbus init or nimbus start.

---

Quick install — pick your platform

Linux (.deb)

Download the .deb, verify its signature, then install it:

# Import the signing key (fingerprint cross-checked in scripts/release/nimbus-verify.sh)
gpg --keyserver keys.openpgp.org --recv-keys 5A20457CCD8B53FFAA945240886ADA6B487CAB6E

# Download the package and its detached signature
curl -fsSL https://github.com/nimbus-agent/Nimbus/releases/latest/download/nimbus_amd64.deb \
  -o /tmp/nimbus.deb
curl -fsSL https://github.com/nimbus-agent/Nimbus/releases/latest/download/nimbus_amd64.deb.asc \
  -o /tmp/nimbus.deb.asc

# Verify BEFORE installing — this step is yours, nothing does it for you
gpg --verify /tmp/nimbus.deb.asc /tmp/nimbus.deb

# Install with apt, NOT `dpkg -i` — the package depends on bubblewrap and
# libcap2-bin, and dpkg will not resolve those for you.
sudo apt install /tmp/nimbus.deb

libsecret-tools is required — credentials live in the OS keystore and the Gateway will not start without it (sudo apt install libsecret-tools).

After installation:

nimbus --version

Without sudo: the one-liner installs the tarball to ~/.local/bin instead. It is x86-64 only — there is no published Linux arm64 build — and it warns about bubblewrap rather than installing it, so you still need sudo apt install bubblewrap libsecret-tools for the Gateway to start. The .deb above is the only path that resolves those dependencies for you.

curl -fsSL https://github.com/nimbus-agent/Nimbus/releases/latest/download/install.sh | sh -s -- --yes

macOS

One command. The installer resolves the latest release, picks Apple silicon or Intel from uname -m, verifies the release signature, and installs to ~/.local/bin:

curl -fsSL https://github.com/nimbus-agent/Nimbus/releases/latest/download/install.sh | sh -s -- --yes

Open a new shell, then:

nimbus --version

Gatekeeper note: macOS will display an “unverified developer” warning the first time the nimbus binary runs. See First-run setup for the one-time bypass step.

Prefer to read the script first?

Download the archive and run the copy inside it — the same installer, no pipe:

# Apple silicon — for Intel, swap arm64 → x64.
curl -fsSL https://github.com/nimbus-agent/Nimbus/releases/latest/download/nimbus-headless-macos-arm64.tar.gz \
  -o /tmp/nimbus.tar.gz
mkdir -p /tmp/nimbus && tar -xzf /tmp/nimbus.tar.gz -C /tmp/nimbus

less /tmp/nimbus/install.sh
/tmp/nimbus/install.sh

Run this way, install.sh installs the binaries extracted alongside it and performs no download, so nothing verifies them for you — check them against the signed SHA256SUMS.asc manifest yourself. See Verify your download.

Windows

Open PowerShell (no administrator required). One command — it resolves the latest release, verifies the release signature, and installs to %LOCALAPPDATA%\Programs\Nimbus\bin:

$url = "https://github.com/nimbus-agent/Nimbus/releases/latest/download/install.ps1"
& ([scriptblock]::Create((irm $url))) -Yes

This works on stock Windows PowerShell 5.1 as well as PowerShell 7. It is spelled & ([scriptblock]::Create(...)) rather than irm ... | iex because iex cannot pass -Yes through to the script.

Open a new PowerShell window, then:

nimbus --version

Prefer a packaged install? nimbus-headless-windows-x64.msi is on the same release page (that one does require administrator).

SmartScreen note: Windows may show an “unrecognised app” warning. Click More info → Run anyway.

Prefer to read the script first?

Download the archive and run the copy inside it — the same installer, no pipe:

$url = "https://github.com/nimbus-agent/Nimbus/releases/latest/download/nimbus-headless-windows-x64.zip"
Invoke-WebRequest -Uri $url -OutFile "$env:TEMP\nimbus.zip"
Expand-Archive -Path "$env:TEMP\nimbus.zip" -DestinationPath "$env:TEMP\nimbus" -Force

notepad "$env:TEMP\nimbus\install.ps1"
& "$env:TEMP\nimbus\install.ps1"

Run this way, install.ps1 installs the binaries expanded alongside it and performs no download, so nothing verifies them for you — check them against the signed SHA256SUMS.asc manifest yourself. See Verify your download.

---

What the installer does

The installer is non-privileged and idempotent on all three platforms.

Installing from a release (the one-liner)

install.sh and install.ps1 work in two modes. When the binaries are sitting beside the script — as they are inside every archive — the script installs those and downloads nothing. When they are not, as with the one-liner, the script fetches the release itself and verifies it before installing:

1. Resolves the latest release tag, or the one you name (--from-release <ver> / -FromRelease <ver>, which forces this mode even when binaries are staged beside the script).
2. Downloads SHA256SUMS and its detached signature SHA256SUMS.asc into a temporary directory.
3. Verifies that signature in a throwaway GPG keyring built for the purpose. The release public key is embedded in the script, and its primary fingerprint 5A20457CCD8B53FFAA945240886ADA6B487CAB6E is pinned there too — no keyserver is contacted, so nothing on the network can substitute a different key. A mismatched fingerprint, or a signing key that is expired or revoked, aborts the install.
4. Downloads the asset for your platform and checks it against the manifest, requiring exactly one manifest line to name that file.
5. Extracts and installs it, then updates your PATH as described below.

Step 3 is skipped in two cases: gpg is not installed or not runnable, or SHA256SUMS.asc cannot be fetched. The install then continues on the checksum alone, but prints SIGNATURE NOT CHECKED and states plainly that the archive was verified against a manifest whose own signature was never established — a checksum pass is never presented as a signature pass. Install gpg first if you want the signature checked. A verification that fails is different from one that is skipped: a mismatched fingerprint, an expired or revoked key, or a checksum mismatch installs nothing at all.

There is deliberately no environment variable that overrides the pinned fingerprint, in either script. Combined with the base-URL override used by our own release tests, one would amount to a complete verification bypass from the environment alone.

Linux

Installed from the .deb:

Item	Location
nimbus, nimbus-gateway	/usr/local/bin/ (thin wrappers; real binaries under /usr/lib/nimbus/bin/)
Gateway data dir	~/.local/share/nimbus/
Shell PATH update	None needed — /usr/local/bin is already on PATH

If you install from the tarball or AppImage instead, install.sh copies the binaries to ~/.local/bin and adds a sentinel marker block to ~/.bashrc, ~/.zshrc or ~/.profile. It checks for that block before writing, so it will not duplicate PATH entries.

macOS

Item	Location
nimbus binary	~/.local/bin/nimbus
Gateway data dir	~/Library/Application Support/nimbus/
Shell PATH update	Sentinel marker block added to ~/.zshrc (and ~/.bash_profile if present)

Windows

Item	Location
nimbus.exe, nimbus-gateway.exe	%LOCALAPPDATA%\Programs\Nimbus\bin\
Gateway data dir	%LOCALAPPDATA%\nimbus\
PATH update	User PATH registry key under HKCU\Environment

The installer performs a case-insensitive PATH segment check before writing — it will not add a duplicate entry if Nimbus\bin is already present.

None of the installers configure autostart on any platform — start the Gateway yourself with nimbus init or nimbus start.

---

Re-running the installer

Both install.sh and install.ps1 are idempotent. Running them again after a successful install:

• Detects the existing installation and upgrades binaries in place.
• Does not create duplicate PATH entries (Linux/macOS: checks for the sentinel marker block; Windows: performs the case-insensitive segment check before writing).
• Does not overwrite your existing data directory or configuration.

To force a fresh install, remove the existing binaries and data directory first, then re-run the script.

---

Uninstall

The release tarball includes a companion uninstall script that reverses every change the installer makes:

Linux / macOS

curl -fsSL https://github.com/nimbus-agent/Nimbus/releases/latest/download/uninstall.sh \
  | bash

Windows

irm https://github.com/nimbus-agent/Nimbus/releases/latest/download/uninstall.ps1 |
  Invoke-Expression

The uninstaller removes binaries, the autostart entry, and the PATH modification. It does not delete your data directory (~/.local/share/nimbus/ on Linux, ~/Library/Application Support/nimbus/ on macOS, %LOCALAPPDATA%\nimbus\ on Windows) — your indexed data and credentials are preserved. Delete that directory manually if you want a complete removal.

---

Verify your download

Before running the installer, you can cross-check the GPG signature and SHA-256 hash of every release artefact. This confirms the bytes you downloaded are the bytes the maintainer signed.

See the full walkthrough: Verify your download.

---

Headless Linux (no desktop session)

Credentials live in the OS keystore, and on Linux that is libsecret talking to a Secret Service provider over D-Bus. Installing libsecret-tools is necessary but not sufficient: the provider also needs a session bus and an unlocked default collection. A server, container, SSH session or WSL install usually has neither, and the Gateway will exit with org.freedesktop.secrets has no default collection.

Run nimbus doctor first — it distinguishes “no session bus”, “no Secret Service provider” and “no default collection”, so you only fix what is missing.

If the machine has never had a login keyring, create one before unlocking. Creating it otherwise escalates to a GUI prompt that a headless box cannot answer:

sudo apt install -y gnome-keyring dbus-x11

mkdir -p ~/.local/share/keyrings
printf '[keyring]\ndisplay-name=login\nctime=0\nmtime=0\nlock-on-idle=false\nlock-after=false\n' \
  > ~/.local/share/keyrings/login.keyring
printf 'login' > ~/.local/share/keyrings/default
chmod 600 ~/.local/share/keyrings/login.keyring

Then start Nimbus inside a session:

dbus-run-session -- bash -c \
  'printf "\n" | gnome-keyring-daemon --unlock --components=secrets; nimbus start'

nimbus doctor should then report [ok] Vault: Secret Service reachable with an unlocked default keyring.

Note

This keyring is unencrypted at rest. That is the standard trade-off for an unattended machine — the secret has to be readable without a human to type a passphrase. On a machine with a real desktop session, log in normally instead and skip all of the above.

AppImage (Linux alternative)

If you prefer a portable single-file executable that does not require dpkg, use the AppImage:

# Download
curl -fsSL \
  https://github.com/nimbus-agent/Nimbus/releases/latest/download/Nimbus-x86_64.AppImage \
  -o ~/bin/nimbus
chmod +x ~/bin/nimbus

# Verify GPG sidecar signature
curl -fsSL \
  https://github.com/nimbus-agent/Nimbus/releases/latest/download/Nimbus-x86_64.AppImage.asc \
  -o /tmp/nimbus.asc
gpg --keyserver keys.openpgp.org --recv-keys 5A20457CCD8B53FFAA945240886ADA6B487CAB6E
gpg --verify /tmp/nimbus.asc ~/bin/nimbus

# Run
nimbus --version

The AppImage is self-contained — no installation step required. PATH management and autostart are your responsibility when using this method.

---

Next steps

Once nimbus --version prints a version number, the fastest path to something useful needs no account, no token, and no API key — index a repository you already have:

cd ~/code/your-project
nimbus init

nimbus init adds the repo to nimbus.toml with code indexing enabled, starts the gateway, indexes the repo, and prints a real file:line from your own code to try with nimbus why. It appends to your config rather than rewriting it, so existing settings and comments survive (and it keeps a nimbus.toml.bak).

Indexing, nimbus why, and the agent briefs all work with no LLM configured. An LLM is needed only for nimbus ask and for prose synthesis of the briefs — see Local & air-gapped LLM setup.

To correlate across cloud services, continue to First-run setup and connect your first service.