1. Overview: What is omicOS
This chapter lays out what omicOS is made of and what the omicos command does, as groundwork for the installation and configuration chapters that follow.
In One Sentence
omicOS combines "large-language-model multi-agent systems" with "single-cell / spatial omics analysis" into one workbench. You describe your analysis intent in natural language, and omicOS's agents call tools like OmicVerse and scanpy, running real code, producing figures and results inside a shared IPython kernel.
This part (Part 1) covers its core, omicos-core: a local program written in Rust, whose command is omicos.
omicos's Dual Identity
The same binary is both a local daemon and a terminal chat client:
- As a daemon, it listens on
http://127.0.0.1:5055on your machine and exposes a set of HTTP + SSE interfaces (/api/*). The web app (app.omicos.cn) connects to it. - As a terminal client (
omicos cli), it opens a chat window directly on the command line — ideal for SSH / HPC environments with no browser.
Either way, all analysis code runs inside the same shared IPython kernel, so the adata object, notebook variables, figures, and file state stay consistent and interchangeable between the web app and the terminal.
Command Overview
| Command | Purpose |
|---|---|
omicos serve |
Starts the HTTP daemon and (by default) opens the browser to the web app. This is the default behavior when no subcommand is given — running plain omicos is equivalent to omicos serve. |
omicos cli |
Starts an embedded daemon plus a terminal chat interface, with no browser required. |
omicos login |
Logs in to your omicOS cloud account with email / password. |
omicos env |
Manages the local Python analysis environment (setup / doctor / list). |
omicos hpc |
Interactive wizard for servers / HPC: pick a Python environment, then start. |
omicos a2a |
Manages the Agent2Agent endpoint and API keys (available in releases after 0.3.29). |
omicos recover-conversations |
Attributes pre-isolation legacy sessions to the current account (operator use, rarely needed day to day). |
Check the version:
omicos --version
Expected output:
omicos 0.3.29+a1b2c3d
The version string follows
<semver>+<git short hash>. Development builds append a(debug)suffix; release builds don't.
For the full flag reference, see Chapter 9: Command & Flag Reference.
How It Connects to the Cloud
After you log in, omicos proactively opens an outbound WebSocket to the omicOS cloud (wss://auth.omicos.cn/ws/process), used for:
- Process registration and heartbeat: lets the cloud know an omicOS process is online on this machine.
- Session and trajectory sync: backs up conversations and analysis trajectories to the cloud, so the record survives after the local process exits.
- Cross-machine access: lets you drive an omicOS instance running on another machine from a browser on your laptop (see the remote deployment recipes).
When you're not logged in, this connection is never established, and the startup banner prints [omicos] offline: run \omicos login` to connect auth.omicos.cn`. Local analysis still works as usual.
Local first. The kernel, data, and notebooks all run on your own machine. The cloud only handles accounts, sync, and access — it never moves your raw data.
Service Domains
| Purpose | Domain |
|---|---|
| Auth / server | auth.omicos.cn |
| Web app | app.omicos.cn |
What This Part Covers
Part 1 is a complete "get omicOS up and running" guide:
- Prerequisites → Installation → Python environment
- Login → Startup (serve / cli)
- Remote / SSH / HPC deployment
- Reference: Command flags, Environment variables, Directory structure
- Advanced: Providers / models, Agents / Skills / Memory
- Troubleshooting
This documentation is based on omicos-core 0.3.29.