License Artifacts

Cor's licensing touches a small, fixed set of artifacts. This page is the complete inventory — what each one is, where it lives, what it is keyed by, and what that means when you move a deployment, split a monorepo, or build a container. Nothing here should ever have to be discovered by archaeology.

The inventory

Resolution order for the key itself: in-memory renewed token → COR_LICENSE_KEY → .soulcraft.json in the current working directory. The legacy spellings (CORTEX_LICENSE_KEY, a cortex key in the file) are still honored.

The one rule that prevents every surprise

Two of the artifacts are working-directory-keyed and one is machine-keyed:

• .soulcraft.json is read from process.cwd() — the directory your app runs from, not where cor is installed. In a monorepo where processes start from different directories (repo root, apps/web/, a worktree), each starting directory needs the file — or set COR_LICENSE_KEY once and the question disappears. The env var is the recommended escape hatch for any multi-directory setup.

• The heartbeat cache (cor ≥ 4.2.0) lives at the machine-keyed home ~/.soulcraft/cor/heartbeat-<fingerprint>.json. It survives fresh checkouts, new worktrees, and redeploys on the same machine. Reads check the machine home first and fall back once to the legacy per-directory location, migrating a hit forward; writes go only to the machine home.

Moving or duplicating a deployment — the checklist

Copying a working deployment to a new directory on the same machine: copy every .soulcraft.json your processes' working directories used (repo root and any app subdirectory), or switch to COR_LICENSE_KEY. The heartbeat cache needs nothing — it is already machine-keyed.

Moving to a new machine: bring the key (env var or file); the heartbeat cache regenerates on first successful heartbeat. If the machine is offline at first boot, cor runs its grace behavior and says so loudly — a silent degrade is a bug, report it.

Containers, CI, and hermetic tests

• Pass the key as COR_LICENSE_KEY — never bake .soulcraft.json into an image.

• COR_LICENSE_CACHE_DIR overrides the machine-keyed cache directory — point it at a writable path in containers with read-only home directories, or at a temp dir in hermetic tests.

• COR_LICENSE_EXCHANGE_URL overrides the exchange endpoint (first-class production override).

What is safe to delete

The heartbeat cache and the legacy .soulcraft/heartbeat.json are always safe to delete — they regenerate. .soulcraft.json holds your key: deleting it de-licenses that working directory (re-run activation or set the env var). Deleting nothing here ever affects your data — license artifacts and brain storage are fully separate.