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.
The desktop app
Section titled “The desktop app”-
Download the installer for your computer (always the newest version):
Windows macOS (Apple silicon) Linux IvoryOS-Setup.exe IvoryOS-arm64.dmg IvoryOS.AppImage Release notes and earlier versions are on the Releases page.
-
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.
Open the
.dmgand drag IvoryOS to Applications. The app is signed and notarized by Apple, so it opens like any other app.Make the file executable and run it:
Terminal window chmod +x IvoryOS.AppImage && ./IvoryOS.AppImage -
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 edge server alone (pip)
Section titled “The edge server alone (pip)”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):
npm install && npm run build:edgepip install edge_server/dist/ivoryos_edge-*.whlor, 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_edgefrom my_lab import SyringePump
pump = SyringePump(port="COM3") # each object becomes an instrument
ivoryos_edge.run(__name__) # http://localhost:8080The 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.