Installing and upgrading with a LumenFlow licence

LumenFlow packages use the private Keygen registry at https://licensing.lumenflow.dev/v1/engines/npm/. The owner decides who receives a free or paid licence. Consumers need no GitHub account, repository access or GitHub seat. GitHub stores the project’s source; it is not the package registry or release runner.

This page retains its former migration URL so existing links keep working.

Configure package access

Obtain a licence and private consumer .npmrc from the owner. Keep the credentials in your user npm configuration or an external private file selected with NPM_CONFIG_USERCONFIG. Do not commit licence keys, Base64 values or API tokens. Base64 is encoding, not encryption.

The project .npmrc may contain this non-secret routing line:

@hellmai:registry=https://licensing.lumenflow.dev/v1/engines/npm/

The private consumer configuration uses a licence key:

@hellmai:registry=https://licensing.lumenflow.dev/v1/engines/npm/
//licensing.lumenflow.dev/:username=license
//licensing.lumenflow.dev/:_password=<base64 licence key supplied by the owner>

An owner-issued token with package read access can instead use //licensing.lumenflow.dev/:_authToken=<token> in the private configuration. Use the authentication method supplied with your grant; do not combine both methods. These forms follow Keygen’s npm engine documentation.

Only @hellmai uses this registry. Other dependencies keep their existing registry. The CLI lets npm resolve project, user and environment configuration on Windows, macOS and Linux. For isolated installs it temporarily copies project configuration with private file permissions, retains user/environment configuration, and restores the isolated file before committing.

Verify that your licence can read actual package metadata:

npm view @hellmai/lumenflow-cli@latest version --registry https://licensing.lumenflow.dev/v1/engines/npm/

The result is the newest release authorized for your licence and may be a prerelease. If the owner supplies an exact release version, use that version when installing. npm whoami is not an access check for this service.

Install in a new project

After configuring access, allow the CLI’s native SQLite dependency to build. With pnpm 10.26 or newer, merge this into the project’s root pnpm-workspace.yaml, keeping existing settings:

allowBuilds:
  better-sqlite3: true

On pnpm 10.0–10.25, add better-sqlite3 to the existing onlyBuiltDependencies list instead. Do not configure both forms; when migrating to allowBuilds, retain existing approvals as true entries. See pnpm’s build settings. Then install the CLI and initialize the project:

pnpm add -D @hellmai/lumenflow-cli
npx lumenflow init

If an earlier install skipped the SQLite build, configure it above and run pnpm rebuild better-sqlite3 before initialization.

Packages contain distribution artifacts. Access controls keep the source repository private, but installed JavaScript can still be inspected. Revoking a licence prevents future downloads; it does not erase an existing installation or prevent someone copying files already downloaded.

If this project adopts the WU lifecycle (wu:claim)

A worktree claim (pnpm wu:claim) needs a canonical git remote configured for the project. Offline or remote-less work uses branch-only claim mode instead; configure the remote first if you want the full worktree lifecycle.

Upgrade an existing project

From the project’s main checkout:

pnpm lumenflow:upgrade --latest --dry-run
pnpm lumenflow:upgrade --latest
pnpm lumenflow:doctor
pnpm gates

Default and --latest upgrades resolve a concrete version from entitled package metadata before mutation. Missing routing, denied access or unavailable metadata stops the real upgrade with remediation. The command does not try another registry. A dry run may show an unresolved preview and an access warning; it does not bootstrap, install, rewrite or migrate state.

Legacy @lumenflow/<name> dependencies migrate to @hellmai/lumenflow-<name> in their existing dependency sections. A partial migration is completed on the default/latest path; an existing published declaration takes precedence over its duplicate legacy key. Other packages are preserved. The command updates the lockfile, bundled pack pins, scripts and managed documentation through its normal governed transaction. Review project-owned imports separately: it does not rewrite source. If this project has lifecycle enforcement enabled, the upgrade command also regenerates the integrity manifest, the same governed step pnpm lumenflow:enable performs; never edit that manifest by hand.

If the installed CLI predates this bridge, run the currently licensed CLI from a temporary package execution environment after configuring access:

pnpm --package=@hellmai/lumenflow-cli dlx lumenflow-upgrade --latest

The temporary execution syntax is documented by pnpm.

An explicit --version 6.1.6 in a legacy-only project keeps its existing @lumenflow/* names and registry. It does not bootstrap the private-scope CLI. Historical availability remains a property of that original registry; this command does not publish, deprecate or remove historical packages.

Package name map

Before (npm)	After (private registry)
@lumenflow/cli	@hellmai/lumenflow-cli
@lumenflow/kernel	@hellmai/lumenflow-kernel
@lumenflow/host	@hellmai/lumenflow-host
@lumenflow/runtime	@hellmai/lumenflow-runtime
@lumenflow/memory	@hellmai/lumenflow-memory
@lumenflow/agent	@hellmai/lumenflow-agent
@lumenflow/initiatives	@hellmai/lumenflow-initiatives
@lumenflow/metrics	@hellmai/lumenflow-metrics
@lumenflow/mcp	@hellmai/lumenflow-mcp
@lumenflow/shims	@hellmai/lumenflow-shims
@lumenflow/surfaces	@hellmai/lumenflow-surfaces
@lumenflow/conductor-sdk	@hellmai/lumenflow-conductor-sdk
@lumenflow/control-plane-sdk	@hellmai/lumenflow-control-plane-sdk
@lumenflow/packs-software-delivery	@hellmai/lumenflow-packs-software-delivery
@lumenflow/packs-agent-runtime	@hellmai/lumenflow-packs-agent-runtime
@lumenflow/packs-campus	@hellmai/lumenflow-packs-campus
@lumenflow/packs-protocol-adapters	@hellmai/lumenflow-packs-protocol-adapters
@lumenflow/packs-reliability-operations	@hellmai/lumenflow-packs-reliability-operations
@lumenflow/packs-sidekick	@hellmai/lumenflow-packs-sidekick

Subpath imports retain their suffix: @lumenflow/kernel/primitives/error-handler becomes @hellmai/lumenflow-kernel/primitives/error-handler.

Access and troubleshooting

Symptom	Action
Wrong or missing @hellmai:registry mapping	Set the project routing line above and retry.
Metadata or download denied	Confirm the configured licence or token, its expiry/suspension status and its package entitlement with the owner.
Registry unavailable	Check connectivity and the licensing service; retry after service is restored.
Dry-run cannot resolve a version	Correct the reported access problem before running a real upgrade.
Old imports still fail	Replace project-owned @lumenflow/* import specifiers using the package map.

Free and paid grants use the same installation mechanism. Payment collection is a separate owner process; selecting a paid grant is not itself a payment or automatic billing integration.