Open-source lab automation.

Gantry motion, instruments, protocols, and experiment data in one system.

Get started · See Operator · Write a protocol · Documentation · Contribute

---

CubOS is an open-source Python control layer for CNC-based lab automation, built and supported by Ursa Labs. It connects GRBL gantry motion, mounted instruments, deck labware, YAML protocols, offline motion validation, and SQLite-backed experiment data into one operator and developer workflow.

Software that reaches the bench

A recorded CubOS hardware demonstration over a 96-well plate.

Prepare	Run	Learn
Define the machine, labware, and steps in readable configs.	Coordinate gantry motion and instrument actions through one protocol engine.	Review saved measurements, run records, and tracked fluid state.

Use the browser for day-to-day operation, YAML or Python to express experiments, and the API to connect other software to your station.

Meet Operator

Operator with PANDA liquid-handling configs and a seeded fluid state. This screenshot shows configuration and visualization; the gantry is disconnected.

See the setup before you run it. Operator brings gantry setup, calibration, deck visualization, protocol editing, validation, and results into the browser. Its fluid-state tools let you define starting contents and inspect the volumes and compositions tracked by CubOS.

Take the Operator tour →

More than motion

Capability	What CubOS provides
Liquid handling	Tip pickup, transfers, mixing, serial transfers, and compound rinse/flush workflows.
Measurement & imaging	Instrument methods at named positions, plate scans, camera capture, and lighting commands.
Offline validation	Schema, protocol semantics, and concrete motion-target checks before hardware connection. Initial-fluid seeds enable liquid-volume simulation.
Experiment records	SQLite-backed measurements, campaign data, run artifacts, and exports for analysis.
Fluid state	Optional persisted volumes, compositions, and tip usage, with reconciliation required after ambiguous interrupted operations.
Extensibility	Instrument interfaces, vendor drivers, labware definitions, and external driver-package registration.

Tracked fluid state describes the software's record of operations; it is not an independent measurement of the liquid on the deck. See fluid tracking, data, and the instrument guide for details and limits.

Quick start

Try an offline setup check first. No gantry connection is needed. These commands use macOS/Linux shell syntax and Python 3.10+ for the core package; Operator requires Python 3.11+.

git clone https://github.com/Ursa-Laboratories/CubOS.git
cd CubOS
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e packages/core

python -m cubos.tools.validate_setup \
  packages/core/configs/gantry/cub_xl_asmi.yaml \
  packages/core/configs/deck/asmi_deck.yaml \
  packages/core/configs/protocol/asmi/move_a1.yaml

Want the browser interface? Follow Getting Started to install the API, build Operator, and launch it. That guide also covers Windows, instrument dependencies, and preinstalled stations.

Looking for workflow configs? Station gantry/deck files and experiment protocols live in the CubOS Protocol Library, organized under cub/, cubxl/, and cubxl_plus/. The Polar Bear workflow includes its configuration snapshots and validation status. See YAML File Overview to select an external config directory. The files used above are bundled examples for learning and offline checks.

Important

CubOS controls real hardware. Before a physical run, commission and calibrate your machine, confirm that the deck matches its configuration, validate the exact setup, check physical clearance, and keep an E-stop reachable. A passing offline check does not establish physical safety or measurement accuracy.

Bring up a machine · Calibrate · Run your first protocol

Connect it to your workflow

Operator, the Python client, and the SiLA 2 service reach the same CubOS HTTP API. The API keeps one persistent gantry session responsible for hardware access and run execution.

Operator browser ──────┐
Python SDK / CLI ──────┼── CubOS HTTP API ── Gantry session ── Hardware
SiLA 2 service ────────┘                         │
                                         Runs & results

• Python SDK & CLI — submit protocol bundles, follow runs, request cancellation, and retrieve artifacts.
• HTTP API — integrate software with the station's versioned /api/v1 interface.
• SiLA 2 — expose administrator-configured protocol presets to lab orchestrators, with progress and artifact retrieval.

Documentation

I want to…	Start here
Install CubOS or open an existing station	Getting Started
Operate a workcell from the browser	Operator guide
Configure a machine and deck	Configuration · Gantry setup · Deck
Calibrate or commission hardware	Calibration · Gantry bring-up
Write an experiment	YAML protocols · Python protocols
Understand recorded state and results	Fluid tracking · Data
Diagnose a problem	Troubleshooting & recovery
Extend CubOS	Contributing · API reference

Built to be opened up

CubOS is MIT licensed. The runtime, Operator, API, Python client, and deployment tooling live together in this repository.

Location	Responsibility
packages/core/	Gantry control, deck geometry, protocols, instruments, validation, and data
services/api/	FastAPI backend and persistent hardware session
apps/operator-web/	Operator browser interface
sdk/python/	Python client and cubos-send command
services/sila/	SiLA 2 integration through the HTTP API
deploy/	Docker, Windows, and Raspberry Pi deployment resources

For developers: install, test, and build the docs

From the repository root, with a Python 3.11+ virtual environment active:

python -m pip install -e "packages/core[dev,docs]"
python -m pip install -e "services/api[dev]" -e "sdk/python[dev]"
python -m pytest packages/core/tests services/api/tests sdk/python/tests -q

npm --prefix apps/operator-web ci
npm --prefix apps/operator-web run lint
npm --prefix apps/operator-web run test -- --run
npm --prefix apps/operator-web run build

python -m mkdocs build --strict
python -m mkdocs serve

The test badge tracks the latest main workflow. The coverage badge describes the CI requirement: at least 90% of added or changed core Python lines must be covered on pull requests. It is not an overall repository coverage percentage.

Use the contribution guide for focused validation and hardware-facing changes. Vendor SDKs are optional extras; install only what your instruments need. Hardware validation is separate from offline software tests.

---

Open-source lab automation.

Built and supported by Ursa Labs · MIT license · Get started