Install¶

pip install cereyan

Cereyan needs Python 3.11 or newer. The wheel is self-contained: it has no runtime dependencies and includes the Rust core and the web UI. Wheels are published for macOS (Apple silicon and Intel), Linux (x86_64 and aarch64, manylinux 2.28), and Windows (x86_64).

pipuv

pip install cereyan

uv add cereyan

Check the install:

cereyan --help
python -c "import cereyan; print(cereyan.__version__)"

What gets created¶

The first run creates the runtime home, ~/.cereyan by default, holding the SQLite database and, later, server.json while a server runs, secret.key once a secret variable exists, and storage/ for persisted results. Set CEREYAN_HOME or pass --home to put it elsewhere; see Engines and the home directory.

Upgrade¶

pip install --upgrade cereyan

The first start of a newer version migrates the database in place. Before it does, the store writes a copy to <home>/backups/pre-migration-v<old>-<time>.sqlite, and refuses to migrate if that copy cannot be written, so there is always a way back: stop the server, put the copy in place of db.sqlite, delete db.sqlite-wal and db.sqlite-shm, and install the older version. A migration that rebuilds a table, such as the task_run rebuild in 2.0.0, makes that start take longer on a large store. A migrated database cannot be opened by an older version, which refuses to start and asks you to upgrade. Read the changelog's Upgrading from list when the major version changes.

Windows¶

The Unix socket listener and engine niceness are Unix-only options, rejected or ignored with a message. Windows cannot interrupt a flow blocked in most I/O calls; a flow running Python code or sleeping in time.sleep is interrupted as on Linux and macOS. Two behaviours are weaker there as a result:

Behaviour	On Windows
A flow's `timeout_seconds` offline (`python pipeline.py`, `cereyan run`) while it is blocked in I/O	The run times out when the call returns. A served run is timed out by the server.
Cancelling a flow blocked in I/O	The engine is ended after the grace period rather than interrupted inside the flow, so `on_cancellation` hooks do not run.

Everything else — the server, the UI, schedules, engines, rules, artifacts, variables, and the MCP server — works the same.

Next: the Quickstart.