3. Installation: via npm

This chapter gets the omicos binary onto your machine. npm automatically downloads the prebuilt binary matching your system — no Rust toolchain required.

3.1 One-Line Install

npm install -g @omicverse/omicos

Verify the install:

omicos --version

Expected output:

omicos 0.3.29+a1b2c3d

--version prints <semver>+<git short hash>. Development builds append a (debug) suffix; release builds don't. To see the full build info (target platform, build profile), query /api/version once the daemon is running:

curl -sS http://127.0.0.1:5055/api/version

Expected output:

{"build_profile":"release","display":"0.3.29+a1b2c3d","git_rev":"a1b2c3d","semver":"0.3.29","target_triple":"aarch64-apple-darwin"}

3.2 How It Works

@omicverse/omicos is a wrapper package that contains no binary itself. It declares six platform-specific subpackages through npm's optionalDependencies, and npm installs only the one matching your os and cpu:

The package's bin/omicos.js is a thin shim that execs the installed native binary at runtime. So when you type omicos, you're running the Rust-compiled binary directly, with no Node runtime overhead.

3.3 Common Questions

Q: command not found: omicos?

The npm global bin directory isn't on your PATH. Find it first:

npm prefix -g

Expected output:

/Users/you/.npm-global

Add its bin subdirectory to PATH (add this to ~/.zshrc or ~/.bashrc to make it permanent):

export PATH="$(npm prefix -g)/bin:$PATH"

Q: Permission error (EACCES)?

Don't use sudo npm install -g. Use a user-level global directory instead:

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @omicverse/omicos

Q: Installed, but no platform subpackage got installed?

Make sure your npm version is recent enough (≥ 7, which handles optionalDependencies correctly) and that you didn't pass --no-optional.

3.4 Upgrading

omicos ships with a built-in auto-updater: at runtime it checks the cloud release manifest, and when it finds a new version it downloads it in the background, verifies it with a SHA-256 checksum, and atomically swaps the binary — taking effect on the next launch. In most cases you don't need to upgrade manually.

To upgrade to the latest version manually:

npm install -g @omicverse/omicos@latest

Confirm the version after upgrading:

omicos --version

Expected output:

omicos 0.3.29+a1b2c3d

Next Steps

With the binary installed, you still need to configure the Python analysis environment before you can actually run analyses — continue to Chapter 4: Configuring the Python Analysis Environment.