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:

Platform Architecture Target triple
Linux x86_64 x86_64-unknown-linux-musl
Linux ARM64 aarch64-unknown-linux-musl
macOS Intel x86_64-apple-darwin
macOS Apple Silicon aarch64-apple-darwin
Windows x64 x86_64-pc-windows-msvc
Windows ARM64 aarch64-pc-windows-msvc

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

Output format (use the version and commit reported by your installation):

omicos <version>+<commit>

2.2 Installation Methods

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

Installation method What you need Who it's for
Install prebuilt package via npm Node.js ≥ 16 All users

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.

Check the Environment in the App

Open Environments from the client's sidebar, find the target workspace, and inspect Execution location at the bottom of its card. These native App screenshots show the full interface with the default light theme and Chinese labels. Personal workspace and environment names and paths are masked; the built-in default environment and status labels remain visible. Click an image to view it at full size.

App environment page: a running kernel with an unavailable Python environment

The kernel is marked running and hot/ready, but the selected Python environment is marked unavailable. Kernel status and analysis-environment status are separate. If you see this warning, prepare the environment as described in Chapter 4 before running analyses.

Click the environment name under execution location to expand the environments detected on this machine:

App execution location: the default environment and detected Conda environments

Names and paths depend on your installation; this is not a list to copy. Detection does not guarantee that omicverse and analysis dependencies are installed. Check the Python version and required packages before selecting an environment.

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:

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.

results matching ""

    No results matching ""