Skip to content

Install

There are two ways to run IvoryOS. The desktop app is the one to pick unless you already have a Python workflow of your own: it manages Python, your decks and driver installs for you.

  1. Download the installer for your computer (always the newest version):

    WindowsmacOS (Apple silicon)Linux
    IvoryOS-Setup.exeIvoryOS-arm64.dmgIvoryOS.AppImage

    Release notes and earlier versions are on the Releases page.

  2. Open it:

    Run the installer. It is signed. Windows can still show “Windows protected your PC” for a newly signed app until it has built up a reputation: choose More info, then Run anyway.

  3. Wait for the first launch to finish. It downloads a Python of its own, so it needs an internet connection and takes about a minute. Nothing is installed into the app bundle itself: Python and every driver live in the app’s data folder (see Where things are on disk).

You land on the welcome page, which offers three things: Try the example (a simulated lab, nothing to plug in), Add a deck (your own instruments) and the Automation Hub. Continue with Try the example.

The deck is a plain Python package, ivoryos-edge. Use it directly when you already have a script that creates your instruments, or on a machine where you want no desktop app. The package carries its web interface, which is built from the repository’s frontend, and it is not on PyPI yet, so build it from a checkout (Python 3.10 or newer, Node.js 22 and uv):

Terminal window
npm install && npm run build:edge
pip install edge_server/dist/ivoryos_edge-*.whl

or, to work on IvoryOS itself, pip install -e ./edge_server after npm --prefix frontend run build.

Then end your script with ivoryos_edge.run(__name__) and run it:

import ivoryos_edge
from my_lab import SyringePump
pump = SyringePump(port="COM3") # each object becomes an instrument
ivoryos_edge.run(__name__) # http://localhost:8080

The page opens at http://localhost:8080 in any browser on that computer. Everything in the user guide applies; only the desktop app chapters do not. Start a deck covers deck files, ports, data folders and the command line.