2. Prerequisites & System Requirements

This chapter helps you confirm your environment before installing. omicOS needs three things: the omicos binary (the program itself), a Python analysis environment (the engine that runs bioinformatics analyses), and an omicOS cloud account.

2.1 Supported Operating Systems & Platforms

omicos ships prebuilt binaries for six platforms:

About Linux: the Linux builds use musl static linking (rather than glibc), which sidesteps compatibility issues caused by differing libc versions across distributions — the same binary runs on Ubuntu, CentOS, and HPC login nodes alike.

Once installed, confirm which platform build you got with omicos --version:

omicos --version

Expected output:

omicos 0.3.29+a1b2c3d

2.2 Installation Methods

omicos is installed by fetching a prebuilt binary via npm, which only requires Node.js ≥ 16:

npm automatically downloads the binary matching your system from the table above — no compiler toolchain required. See Chapter 3 for details.

2.3 Python Analysis Environment

omicos itself is just a scheduling kernel — the thing that actually runs scanpy / omicverse is a separate Python environment (Python 3.11 + omicverse, about 1.5 GB).

• The recommended approach is to create it in one step with omicos env setup (which manages the virtual environment under the hood with uv).
• You can also point it at an existing conda / venv environment.

See Chapter 4: Configuring the Python Analysis Environment for details.

Note: environment problems surface lazily. Without a configured environment, omicos serve still starts fine and chat still works — it prepares the environment in the background without blocking startup. You'll only see Python environment unavailable: … (or The Python environment is still being prepared… while it's still installing) once you actually try to run analysis code. So set up the environment ahead of time, rather than discovering the gap mid-analysis.

2.4 omicOS Cloud Account

Agent chat, cross-device viewing, image hosting, and subscription tiers all depend on a cloud account:

• Register at auth.omicos.cn.
• See Chapter 5 for sign-in methods.

2.5 Network Requirements

• omicos needs access to auth.omicos.cn for login, process registration, and syncing.
• By default it only listens on 127.0.0.1 and exposes no public ports; remote access is done through SSH port forwarding — see the remote deployment recipes for details.
• If your machine is behind an HTTP proxy, allow-list the loopback address (export no_proxy=localhost,127.0.0.1). Otherwise the proxy may intercept the kernel's outbound requests and the browser's connection to localhost:5055, showing up as "it just won't connect." omicos prints a bilingual warning at startup when it detects this kind of configuration.

Checklist

Before you start installing, confirm:

• [ ] Your OS is one of the six platforms above
• [ ] Node.js ≥ 16 is installed
• [ ] You've registered an account at auth.omicos.cn
• [ ] The machine has internet access (at minimum, it can reach auth.omicos.cn)

Once these are met, move on to Chapter 3: Installing via npm.