Configuration

The runtime has no configuration file of its own. You configure it with a few environment variables, the location of your license file, and command-line flags. This page lists all of them.

Runtime 0.3.1

Environment variables#

Variable	Read by	Default	Meaning
`HELIXOR_LICENSE_FILE`	`helixor-pack`; `load_pack` and pack unsealing when no license is passed; the generated SDK client	unset	Path to your `.hxlic` file.
`HELIXOR_AUTHORITY_URL`	`helixor-pack compile --remote`, `catalog`, `download-pack`	see next row	Base URL of the Helixor licensing and compiler authority. A trailing `/` is removed.
`HELIXOR_ENVIRONMENT`	same	`development`	Picks the authority when `HELIXOR_AUTHORITY_URL` is unset: `prod` or `production` selects `https://license.helixor.dev`; anything else selects `https://license-dev.helixor.dev`. Set it to `production` in production.
`HELIXOR_RUNTIME_LIB`	Generated SDK client	unset	Path to a native runtime library. No native library ships in 0.3.1 (Planned), so this has no effect today.
`HELIXOR_SERVICE_TOKEN`	The decision service (`helixor-pack serve`, `start_server`, `python -m helixor_runtime.server`)	unset	Bearer token required on every endpoint except `GET /v1/health`, when no token is passed explicitly. Required to bind a non-loopback address.
`HELIXOR_CORS_ORIGINS`	The decision service	unset (no cross-origin access)	Comma-separated browser origins allowed to call the service, with credentials. An origin containing `*` is rejected at startup.

Evaluation itself (HelixorEngine() and evaluate()) reads no environment variables.

Some hosted-API example scripts read HELIXOR_API_URL and HELIXOR_API_KEY. Those belong to the scripts, not to the runtime; see Hosted escalation.

License search order#

The helixor-pack commands, HelixorEngine.load_pack, the decision service and HelixorSolver share one search order:

The explicit path: --license (or the positional path for inspect-license), or license_file=.
$HELIXOR_LICENSE_FILE.
./helixor.hxlic in the working directory.
~/.helixor/helixor.hxlic.

The search stops at the first entry that is set: an explicit path or $HELIXOR_LICENSE_FILE naming a missing file is an error, not a reason to look further. The older name helixor.lic is still accepted in the two directories; a directory with both names raises LicenseLocationAmbiguousError (LICENSE_LOCATION_AMBIGUOUS). No license anywhere raises LicenseNotFoundError (LICENSE_NOT_FOUND, also a FileNotFoundError), and the CLI exits 1 with the same message. HelixorEngine() searches nothing: it always uses the built-in Community license.

Changed in 0.3.1

In 0.3.0 the CLI and the Python loaders searched different places, only the CLI looked in the working directory, and unsealing a pack with no license raised PackUnsealError.

To get the same behavior regardless of the working directory, set HELIXOR_LICENSE_FILE to an absolute path. Keep the file readable only by the service account (chmod 600); it contains your pack content key. See License file.

.env auto-loading#

The CLI, and the modules that compile or unseal packs, load one .env file when they are first imported. They look in this order and use the first file found:

./.env in the working directory
../.env in the parent directory
~/.helixor/.env

Each line is KEY=VALUE. Blank lines and lines starting with # are skipped, and surrounding quotes are removed. A variable that is already set in the environment is not overridden.

Side effect

Loading copies every variable in that .env file into the process environment, not only HELIXOR_* ones. That includes an application's .env one directory up. In production, set variables explicitly and run from a working directory with no .env in it or its parent. Evaluation with HelixorEngine() alone does not trigger the load.

Ports and bind addresses#

Started by	Default	Change with
`helixor-pack serve`	`0.0.0.0:18734`	`--host`, `--port`
`start_server()`	`127.0.0.1`, a free port chosen at start	`host=`, `port=`

The service has no authentication and allows any CORS origin. Bind to 127.0.0.1 or a private interface. See HTTP API and Security.

Outbound network#

Evaluation, streaming, run and serve make no outbound connections. Only compile --remote, catalog and download-pack contact the authority, over HTTPS, and they send your license JSON. In an air-gapped deployment, compile locally and copy the pack in. See Deployment patterns.