Installation

The runtime is a Python package with a command-line tool. It installs into any virtual environment and needs no service, database or network access to evaluate. The Quickstart installs it into a clone of the helixor-decision-demos repository; this page has the details.

Requirements#

Requirement	Details
Python	3.11 or 3.12; both were verified with the demo repository on 2026-09-29. 3.10 and 3.13 are not verified. Python 3.14 is not yet supported.
Operating system	macOS (Apple silicon, Intel), Linux (x86_64, aarch64), Windows through WSL.
Dependencies	Installed automatically: `pydantic` 2, `cryptography`, `pyyaml`, and `fastapi`, `uvicorn` and `websockets` for the HTTP service.
Optional	The `gpu` extra (`torch` and `numpy`), only for the GPU batch constraint solver. Not needed for evaluation; importing `helixor_runtime` loads neither.

Changed in 0.3.0

The wheel declares Python 3.11 or later, and pip refuses it on older versions with "requires a different Python". Wheels labelled 0.2.1 declared 3.9 but failed at import on it.

Install the package#

Not on the public package index yet

Publishing helixor-runtime to the public index is Planned. Until then you install the wheels you receive when your license request is approved: the runtime and the constraint-network wheel it depends on, with a SHA256SUMS file that lists the checksum of each. Install both in one pip install; installing the runtime wheel alone makes pip look for the dependency on the public index. Check the checksums before you install (see SDK downloads). The package name, import paths and CLI are the same either way, so nothing in these docs changes when the public package ships.

python3.12 -m venv .venv
source .venv/bin/activate
shasum -a 256 ~/Downloads/helixor_runtime-0.3.1-py3-none-any.whl \
              ~/Downloads/helixor_constraint_network-1.0.1-py3-none-any.whl   # or sha256sum
pip install ~/Downloads/helixor_constraint_network-1.0.1-py3-none-any.whl \
            ~/Downloads/helixor_runtime-0.3.1-py3-none-any.whl

python3.12 -m venv .venv
source .venv/bin/activate
pip install helixor-runtime

Add the solver engines (embedded model)#

HelixorSolver(mode="embedded", ...) runs the solver engines in your process. They are planned to ship as a third licensed wheel, helixor_solvers, in the private release (Planned; the 0.3.1 release does not include it). It needs Python 3.12 or later, and like the other two wheels it is not on any package index. Without it, an embedded solve raises SolverEngineUnavailableError. The hosted model, HelixorSolver(mode="hosted", ...), does not need it. Running the engines in your process also needs an Enterprise license carrying the solver.embedded feature; see the license file reference.

Each release carries a SHA256SUMS file that covers every wheel in it. Once a release includes the solver wheel, verify the digests, then install all three wheels in one command:

sha256sum -c SHA256SUMS          # or: shasum -a 256 -c SHA256SUMS
pip install ./helixor_constraint_network-1.0.1-py3-none-any.whl \
            ./helixor_runtime-0.3.1-py3-none-any.whl \
            ./helixor_solvers-0.7.0-py3-none-any.whl

The install provides two import packages and two commands:

Name	What it is
`helixor_runtime`	The public API: `HelixorEngine`, the service helpers and the generated models. Import from here.
Implementation modules	Other packages installed alongside `helixor_runtime` are internal. Do not import them; they can change without notice.
`helixor-pack`, `helixor`	The same CLI under two names: inspect licenses, compile playbooks, run and serve packs. See the CLI reference.

Verify#

python -c "import helixor_runtime as h; e = h.HelixorEngine(); print(h.__version__, e.pack_id, e.tier)"

0.3.1 compliance.regulatory_pii_guard.v1 COMMUNITY

Place your license file#

The Community tier needs no license file. Licenses are issued by Helixor; request one on the sign-up page. The CLI cannot mint or sign a license. For Developer and higher tiers, the CLI and every Python loader look for your license in this order and use the first one they find:

A path you pass explicitly (--license, or the license_file argument).
The HELIXOR_LICENSE_FILE environment variable.
./helixor.hxlic in the working directory.
~/.helixor/helixor.hxlic.

The file name helixor.lic that runtime 0.3.0 used is still accepted in those two directories. A directory that holds both names raises LicenseLocationAmbiguousError (LICENSE_LOCATION_AMBIGUOUS). When no license is found, the runtime raises LicenseNotFoundError (LICENSE_NOT_FOUND, also a FileNotFoundError), whose message lists the six locations it checked and where to request a license. An explicit path or HELIXOR_LICENSE_FILE that does not exist is an error too; the search does not continue past it.

mkdir -p ~/.helixor
mv ~/Downloads/<your-license-id>.hxlic ~/.helixor/helixor.hxlic
chmod 600 ~/.helixor/helixor.hxlic
helixor-pack inspect-license

Before the license is in place, inspect-license exits with status 1 and prints:

Error: LICENSE_NOT_FOUND: no Helixor license file was found.
Locations checked, in order:
  1. --license / license_file= (not given)
  2. $HELIXOR_LICENSE_FILE (not set)
  3. /home/you/project/helixor.hxlic
  4. /home/you/project/helixor.lic (legacy name)
  5. /home/you/.helixor/helixor.hxlic
  6. /home/you/.helixor/helixor.lic (legacy name)
The Community tier needs no license. For a Developer or Enterprise license, request one at https://helixor.dev/signup/index.html (see https://helixor.dev/guide/account.html#request-access).
Save the .hxlic file you receive as ~/.helixor/helixor.hxlic (chmod 600), or pass --license <path> / license_file=<path>, or set HELIXOR_LICENSE_FILE=<path>.

Changed in 0.3.1

The canonical file name is helixor.hxlic, and the Python loaders now search the working directory as the CLI does; in 0.3.0 they skipped it. A missing license raises LicenseNotFoundError from every entry point. The mint-license command is removed.

Treat the license as a secret

A license file contains the key that decrypts the packs issued for it. Store it the way you store a database password: file mode 600 on hosts, a secret manager in containers. See Security.

Install the CLI only#

The wheel installs the helixor-pack and helixor commands into the virtual environment's bin directory. On a machine that only needs the CLI (a build agent that compiles packs, for example), install the wheel into its own virtual environment and call the commands from there:

python3.12 -m venv /opt/helixor
/opt/helixor/bin/pip install ./helixor_constraint_network-1.0.1-py3-none-any.whl ./helixor_runtime-0.3.1-py3-none-any.whl
/opt/helixor/bin/helixor-pack --help

Uninstall#

pip uninstall helixor-runtime

Your license in ~/.helixor/helixor.hxlic is left in place. Delete it separately if you no longer need it.