Documentation Status PyPI version Downloads License YouTube YouTube Published Community

IvoryOS logo

IvoryOS: open-source orchestrator for self-driving labs

IvoryOS turns existing Python automation code into interactive controls, drag-and-drop workflows, and optimization-ready experiments.

Build for fast-changing R&D environments, and make Python-based lab automation accessible and scalable.

code_launch_design.png

Join our community!

IvoryOS is an open-source project under active development. We welcome feedback, feature ideas, and contributions from anyone working on or interested in self-driving laboratories.

Join our Discord or Slack to ask questions, share use cases, and help shape IvoryOS.

Table of Contents

Installation

From PyPI:

pip install ivoryos

System Requirements

Platforms: Compatible with Linux, macOS, and Windows (developed/tested on Windows).
Python: Python ≥3.10

Dependency groups
  • Core: Flask, Flask-Login, Flask-Session, Flask-SocketIO, Flask-SQLAlchemy, Flask-WTF, WTForms, SQLAlchemy-Utils, bcrypt, python-dotenv, pandas.
  • Optimizers: optimizer-ax, optimizer-baybe, optimizer-nimo, or optimizers for all supported optimizer adapters.
  • Database: db for PostgreSQL support.
  • LLM design agent: llm for the optional in-app text-to-workflow feature.
  • Development: dev for running the test suite.
Optional feature installs 
pip install "ivoryos[optimizers]"       # all optimizer adapters
pip install "ivoryos[optimizer-ax]"     # Ax only
pip install "ivoryos[optimizer-baybe]"  # BayBE only
pip install "ivoryos[optimizer-nimo]"   # NIMO only
pip install "ivoryos[db]"               # PostgreSQL support
pip install "ivoryos[llm]"              # optional text-to-workflow design agent

From a local source checkout:

pip install -e ".[dev]"
pytest
32-bit Windows installation notes

Prefer 64-bit Python when possible. If you must deploy IvoryOS on 32-bit Windows, pip may not find pre-built 32-bit wheels for modern packages such as greenlet, pandas, or newer Flask-Session releases.

# 1. Use a Flask-Session release before the msgspec dependency.
pip install "Flask-Session<0.7"

# 2. Install a pandas wheel compatible with the local 32-bit Python environment.
pip install pandas --user --only-binary=:all:

# 3. Install greenlet from conda-forge if PyPI has no compatible wheel.
conda install -c conda-forge greenlet -y

# 4. Install IvoryOS.
pip install ivoryos

Quick start

In your script, where you initialize or import your robot:

my_robot = Robot()

import ivoryos

ivoryos.run(__name__)

Then run the script and visit http://localhost:8000 in your browser. Use admin for both username and password, and start building workflows!

Features

Direct control:

direct function calling Instruments tab

Workflows

  • Design Editor: drag/add function to canvas in Workflow tab, use #parameter_name for dynamic parameters, click Prepare Run button to go to the execution configuration page
  • Execution Config: configure iteration methods and parameters in Execution tab.
  • Design Library: manage workflow scripts in Library tab.
  • Workflow Data: Execution records are in Data tab.
Logging

Add single or multiple loggers:

ivoryos.run(__name__, logger="logger name")
ivoryos.run(__name__, logger=["logger 1", "logger 2"])
Human-in-the-loop

Use pause in flow control to pause the workflow and send a notification with custom message handler(s). When run into pause, it will pause, send a message, and wait for human's response. Example of a Slack bot:

def slack_bot(msg: str = "Hi"):
    """
    a function that can be used as a notification handler function("msg")
    :param msg: message to send
    """
    from slack_sdk import WebClient

    slack_token = "your slack token"
    client = WebClient(token=slack_token)

    my_user_id = "your user id"  # replace with your actual Slack user ID

    client.chat_postMessage(channel=my_user_id, text=msg)

import ivoryos
ivoryos.run(__name__, notification_handler=slack_bot)

Use Input in flow control to get human input during workflow execution. Example:

click to see the data folder structure
  • ivoryos_data/:
    • config_csv/: Batch configuration csv
    • pseudo_deck/: Offline deck .pkl
    • results/: Execution results
    • scripts/: Compiled workflows Python scripts
    • default.log: Application logs
    • ivoryos.db: Local database

Demo

Online demo at demo.ivoryos.ai. Local version in abstract_sdl.py

Roadmap

Check out our Work Items for upcoming features and improvements.

  • Support dataclass input
  • Introspection version control
  • Check config file compatibility

Contributing

We welcome all contributions — from core improvements to new drivers, plugins, and real-world use cases. See CONTRIBUTING.md for details.

Citing

Click to see citations

If you find this project useful, please consider citing the following manuscript:

Zhang, W., Hao, L., Lai, V. et al. IvoryOS: an interoperable web interface for orchestrating Python-based self-driving laboratories. Nat Commun 16, 5182 (2025).

@article{zhang_et_al_2025,
  author       = {Wenyu Zhang and Lucy Hao and Veronica Lai and Ryan Corkery and Jacob Jessiman and Jiayu Zhang and Junliang Liu and Yusuke Sato and Maria Politi and Matthew E. Reish and Rebekah Greenwood and Noah Depner and Jiyoon Min and Rama El-khawaldeh and Paloma Prieto and Ekaterina Trushina and Jason E. Hein},
  title        = {{IvoryOS}: an interoperable web interface for orchestrating {Python-based} self-driving laboratories},
  journal      = {Nature Communications},
  year         = {2025},
  volume       = {16},
  number       = {1},
  pages        = {5182},
  doi          = {10.1038/s41467-025-60514-w},
  url          = {https://doi.org/10.1038/s41467-025-60514-w}
}

For an additional perspective related to the development of the tool, please see:

Zhang, W., Hein, J. Behind IvoryOS: Empowering Scientists to Harness Self-Driving Labs for Accelerated Discovery. Springer Nature Research Communities (2025).

@misc{zhang_hein_2025,
  author       = {Wenyu Zhang and Jason Hein},
  title        = {Behind {IvoryOS}: Empowering Scientists to Harness Self-Driving Labs for Accelerated Discovery},
  howpublished = {Springer Nature Research Communities},
  year         = {2025},
  month        = {Jun},
  day          = {18},
  url          = {https://communities.springernature.com/posts/behind-ivoryos-empowering-scientists-to-harness-self-driving-labs-for-accelerated-discovery}
}

Acknowledgements

Authors acknowledge Telescope Innovations Corp., UBC Hein Lab, and Acceleration Consortium members for their valuable suggestions and contributions.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.6.10)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ivoryzhang from gravatar.com ivoryzhang

Credits

Author: Ivory Zhang

License

MIT

Requires

Python >=3.7

Provides Extra

optimizer-ax optimizer-baybe optimizer-nimo db llm optimizers doc dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ivoryos-1.6.8.tar.gz (465.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ivoryos-1.6.8-py3-none-any.whl (511.4 kB view details)

Uploaded Python 3

File details

Details for the file ivoryos-1.6.8.tar.gz.

File metadata

  • Download URL: ivoryos-1.6.8.tar.gz
  • Upload date:
  • Size: 465.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.10.20

File hashes

Hashes for ivoryos-1.6.8.tar.gz
Algorithm Hash digest
SHA256 a24a7f18585438e31fe605826ea2ddd2fe8d321dd68cf48345936e04e757716a
MD5 41254d7c370d5040a31f0a1612b284ab
BLAKE2b-256 d060686a9c0a87fc66d7f9e20df36b83c4d136147afbea4dd23af4ae33a893c0

See more details on using hashes here.

File details

Details for the file ivoryos-1.6.8-py3-none-any.whl.

File metadata

  • Download URL: ivoryos-1.6.8-py3-none-any.whl
  • Upload date:
  • Size: 511.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.10.20

File hashes

Hashes for ivoryos-1.6.8-py3-none-any.whl
Algorithm Hash digest
SHA256 8986220b739208a6b3520928c5f5ad31c09ca2ed2463fd90b0fe4acd7e050de5
MD5 9f0d7dfb2b151c482e9b31893379c6aa
BLAKE2b-256 63c9b14b3a79a9fdc545b94b6e5a26a88ad95abda3d3301ff00a36fc57a8a5e2

See more details on using hashes here.

Release history Release notifications | RSS feed

1.6.10

2 files

1.6.9

2 files

This release

1.6.8 This release

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.21

2 files

1.5.20

2 files

1.5.19

2 files

1.5.18

2 files

1.5.17

2 files

1.5.16

2 files

1.5.15

2 files

1.5.14

2 files

1.5.13

2 files

1.5.12

2 files

1.5.11

2 files

1.5.10

2 files

1.5.9

2 files

1.5.8

2 files

1.5.7

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.16

2 files

1.4.15

2 files

1.4.14

2 files

1.4.13

2 files

1.4.12

2 files

1.4.11

2 files

1.4.10

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.9

2 files

1.3.8

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

Pre-release

1.3.5a0

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

Pre-release

1.3.0a0

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

Pre-release

1.2.6a0

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.0

2 files

Pre-release

1.2.0b1

2 files

1.1.0

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.1

2 files

1.0.0

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

1 file

0.1.16

1 file

0.1.15

1 file

0.1.14

1 file

0.1.13

1 file

0.1.12

2 files

0.1.11

1 file

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page