1. Overview: What is omicOS
In One Sentence
omicOS is a workbench that combines "large-language-model multi-agent systems" with "single-cell / spatial omics analysis." You describe your analysis intent in natural language, and omicOS's team of agents automatically calls tools like OmicVerse and scanpy, producing real code, figures, and results inside a shared IPython kernel.
This part (Part 1) is about its "core"—omicos-core: a local program written in Rust. Understanding its role is the foundation for getting the most out of omicOS.
omicos-core's Dual Identity
The single omicos binary is both a local daemon and a terminal chat client (TUI):
- As a daemon, it listens on
http://127.0.0.1:5055on your machine and exposes a stable set of HTTP + SSE interfaces (/api/*). The web SPA (app.omicos.cn) connects to it. - As a terminal client, it opens a chat window directly on the command line (
omicos cli), which is ideal for SSH / HPC environments that have no browser.
Whichever identity it takes, all analysis code runs inside the same shared IPython kernel, so the adata object, notebook variables, figures, and file state are fully consistent and interchangeable between the web and the terminal.
Four Run Modes
The omicos command has four subcommands, corresponding to four things:
| Command | Purpose |
|---|---|
omicos serve |
Starts the HTTP daemon and (by default) opens the browser to the web frontend. 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 (TUI), with no browser required. |
omicos login |
Logs in to your omicOS cloud account. |
omicos env |
Manages the local Python analysis environment (install / diagnose). |
How It Connects to the Cloud
omicos-core proactively connects to omicOS's cloud ProcessHub over an outbound WebSocket (wss://auth.omicos.cn/ws/process), which is used for:
- Process registration and heartbeat: lets the cloud know "there is an omicOS process online on this machine."
- Session and trajectory sync: backs up conversations and analysis trajectories to the cloud, so the records remain even if the local process exits.
- Cross-machine relay: lets you operate an omicOS instance running on a remote server from the browser on your laptop (see the Remote deployment recipe for details).
Important: local first. The kernel, data, and notebooks all run on your own machine. The cloud only handles accounts, sync, and relay—it never moves your raw data away.
Service Domains
omicOS's cloud services consistently use:
| Purpose | Domain |
|---|---|
| Auth / server | auth.omicos.cn |
| Web SPA | app.omicos.cn |
What This Part Covers
Part 1 is a complete "get omicOS up and running" guide, covering in order:
- Prerequisites → Installation → Python environment
- Login → Startup (serve / cli)
- Remote / SSH / HPC deployment
- Reference material: Command flags, Environment variables, Directory structure
- Advanced: Providers / models, Agents / Skills / Memory
- Troubleshooting
This documentation is based on omicos-core v0.2.18.