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.9.tar.gz (466.6 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.9-py3-none-any.whl (512.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: ivoryos-1.6.9.tar.gz
  • Upload date:
  • Size: 466.6 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.9.tar.gz
Algorithm Hash digest
SHA256 309a3da1587ecd7182e0df5a10a23e69b1c4bc42bf963baf4c6bf427d3cb6ccb
MD5 2007d42c9b4b818920b6cf3bd53d80d8
BLAKE2b-256 0dba86305f5aa626429908415aa8c7c8c01630fcd69a5ff50ff597399e6871ac

See more details on using hashes here.

File details

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

File metadata

  • Download URL: ivoryos-1.6.9-py3-none-any.whl
  • Upload date:
  • Size: 512.3 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.9-py3-none-any.whl
Algorithm Hash digest
SHA256 bdac1bab2b1a0eee7f7f02ad709b0defd53fb9073615993111dfb1bb08cd2c3d
MD5 c27074bb228f1172d066e9c35e046bce
BLAKE2b-256 2ae7e631754447515b8b48007ad62bbd36e567a6e94ca7dab3f6b71bf4dee409

See more details on using hashes here.

Release history Release notifications | RSS feed

1.6.10

2 files

This release

1.6.9 This release

2 files

1.6.8

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