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.2.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.2.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#

Caller	Order
`helixor-pack` commands	`--license` (or the positional path for `inspect-license`) → `$HELIXOR_LICENSE_FILE` → `./helixor.lic` → `~/.helixor/helixor.lic`. It stops at the first entry that is set; if that file is missing, the command exits 1.
Pack unsealing with no license argument	`$HELIXOR_LICENSE_FILE` → `~/.helixor/helixor.lic`. The working directory is not searched. With neither, it fails with `PackUnsealError`.
`HelixorEngine.load_pack`	Its `license_file` argument; without it, the same order as pack unsealing above. A `license_file` that does not exist raises `FileNotFoundError`.
`HelixorEngine()`	None. Always the built-in Community license.

To get the same behavior everywhere, 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.