> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get access and install

> Point your package manager at the Stackra registry, install the free @stackra packages, and add a licence token for @stackra-pro.

Every Stackra package is served by one npm-compatible registry, `https://npm.stackra.figentra.com/`
([ADR 0453](https://docs.stackra.figentra.com/adr/0453-the-stackra-registry-one-npm-compatible-store-on-cloudflare-and-our-own-licence-engine.md)). It
holds two scopes:

| Scope | Licence | Who can install |
| - | - | - |
| `@stackra/*` | MIT ([0024](https://docs.stackra.figentra.com/adr/0024-mit-license-with-exclusions.md)) | anyone, no account and no token |
| `@stackra-pro/*` | commercial; minified `dist` and types only, no source ([0316](https://docs.stackra.figentra.com/adr/0316-open-core-distribution.md)) | a holder of a licence token whose licence covers the package |

The registry never proxies npmjs: it answers only for these scopes, so every other dependency keeps coming from your
usual registry.

> [!NOTE]
>
> Status, 2026-10-29: the registry is built and the release workflow publishes to it. Version `0.1.0` is not released
> yet, so `latest` is absent; prereleases go out under the `next` dist-tag (the tooling presets first). Check what is
> there with `npm view @stackra/<name> dist-tags --registry https://npm.stackra.figentra.com/`.

## Requirements

* Node.js 24 or later (`engines` in every package).
* npm, pnpm or Yarn. Packages are ESM only (`dist/*.mjs` with `.d.mts` types); there is no CommonJS build
  ([0025](https://docs.stackra.figentra.com/adr/0025-packages-publish-to-private-registry.md) decision 3).

## Install the free packages

**1. Map the scope**

Add one line to the `.npmrc` at the root of your project and commit it:

```ini theme={"system"}
@stackra:registry=https://npm.stackra.figentra.com/
```

**2. Install**

```bash theme={"system"}
pnpm add @stackra/container
```

A token sent for `@stackra` is ignored, so a wrong or revoked token never breaks a free install.

## Install Pro packages

**1. Get a licence token**

A Pro licence is issued by Figentra when you buy it; each licence carries one or more tokens. A token looks like
`stkl_` followed by 43 characters. It is shown once, when it is issued; Figentra keeps only its hash, so a lost
token is replaced, never recovered.

> [!WARNING]
>
> **Owner to supply (STA-1576):** how a customer buys a licence and asks for a token (form, email or account
> page), and who to contact. Not decided yet.

Ask for one token per machine or CI system and give each a label. A licence holds up to 20 live tokens (the
registry's default setting), and each can be revoked on its own.

**2. Map both scopes and name the token**

```ini theme={"system"}
@stackra:registry=https://npm.stackra.figentra.com/
@stackra-pro:registry=https://npm.stackra.figentra.com/
//npm.stackra.figentra.com/:_authToken=${STACKRA_LICENCE_TOKEN}
```

Commit this file: it names the environment variable, never the value. Set the variable in your shell or your
secret manager. The Stackra CLI (`stackra add`) reads the same name.

**3. Check the token**

```bash theme={"system"}
curl -fsS -H "Authorization: Bearer $STACKRA_LICENCE_TOKEN" \
  https://npm.stackra.figentra.com/-/stackra/v1/entitlements
```

The answer is `{ holder, grants, expiresAt, status }`: the scopes and names the licence may read, and until when.
`npm whoami --registry https://npm.stackra.figentra.com/` prints the holder.

**4. Install**

```bash theme={"system"}
pnpm add @stackra-pro/<name>
```

What Pro holds for 0.1.0 is decided in
[0461](https://docs.stackra.figentra.com/adr/0461-the-pro-line-for-0-1-0-runtime-free-behind-entitlements-paid-studios-and-advanced-drivers.md): paid
studio UIs and advanced drivers over free runtimes. Runtime code stays free; a paid runtime feature is a plan
entitlement, not a package.

## In CI

Store the token as a secret of your CI system named `STACKRA_LICENCE_TOKEN` and expose it to the install step. Use a
token issued for that CI system, not a developer's. GitHub Actions:

```yaml theme={"system"}
- name: Install
  run: pnpm install --frozen-lockfile
  env:
    STACKRA_LICENCE_TOKEN: ${{ secrets.STACKRA_LICENCE_TOKEN }}
```

A job that installs only `@stackra/*` needs no secret.

## What the registry answers

| You see | Means | Do |
| - | - | - |
| `401` on a `@stackra-pro` package | no token, or a token the registry does not know (mistyped, or revoked) | check `STACKRA_LICENCE_TOKEN` is set where you install |
| `403` on a `@stackra-pro` package | the licence does not cover that name, is suspended or revoked, or expired more than the grace days ago | check the entitlements call above; contact Figentra |
| `403` on `npm login` | there is no login: access is the licence token | use the `.npmrc` above |
| `404` | the name is not on the registry (the registry never fetches from npmjs) | check the scope mapping and the spelling |

## Licence lifecycle

* A revoked token or licence stops working everywhere within about a minute (the registry caches a token check for 60
  seconds by default).
* After `expiresAt` the licence keeps reading for a grace period (14 days by default), then reads stop.
* Suspension, revocation and expiry never touch what you already installed: nothing in a package calls home
  ([0076](https://docs.stackra.figentra.com/adr/0076-every-package-runs-saas-on-prem-and-air-gapped.md)).
* An expired licence does not keep access to versions released before it expired (0453, "Decided, with triggers" 2).
* To rotate a token: get the new one, switch your secret, then ask for the old one to be revoked.

## Check what you installed

Every version carries a registry signature, and the registry publishes its keys in npm's format, so npm can check
them:

```bash theme={"system"}
npm audit signatures
```

Each version also has a Sigstore provenance bundle tying the tarball to the release workflow run that built it,
served at `https://npm.stackra.figentra.com/-/npm/v1/attestations/@scope%2fname@<version>`. See
[Security overview](https://docs.stackra.figentra.com/customers/security.md) for the whole chain.

## Not ready yet

| Item | State |
| - | - |
| The Pro licence text (`LICENSE` of `@stackra-pro/*`) | pending, owner (STA-30) |
| Whether a Pro package checks its licence at runtime | pending, owner (STA-1589); today access is gated at install only |
| How to buy a licence and request tokens | pending, owner (STA-1576) |
| `stackra whoami` (the entitlements call from the CLI) | not built; use the `curl` call above |
| A signed offline licence file for on-prem and air-gapped installs | not built (0453 decision 15) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.