Package access
The Modem SDK packages use the @preternatural-js scope on GitHub Packages, not anonymous public npm access. Configure this once in the application that will install them. A Modem admin API key or CLI login does not authenticate a package manager to GitHub.
Get read access
Your GitHub account needs read access to the packages, including their private dependencies. Ask the package owner to grant access if necessary. A repository invitation alone may not grant package access when its permissions are configured separately. See GitHub package permissions .
For local installation, use a personal access token (classic) with read:packages and the required account access. Publishing/deletion scopes are not needed to install. Follow your organization’s token and SSO authorization requirements. GitHub documents the supported token type in its npm registry guide .
Configure the registry
Create or merge this .npmrc beside your application’s root package.json:
@preternatural-js:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}Keep the ${GITHUB_TOKEN} reference literal in this file; never replace it with a real token in a committed file. The scope mapping leaves unrelated packages on their normal registry. The same configuration covers private @preternatural-js dependencies such as api-schema.
Supply GITHUB_TOKEN to the package-manager process through your secret manager or an untracked local environment file. For Bun, a local .env.local can contain:
GITHUB_TOKEN=YOUR_GITHUB_PACKAGES_READ_TOKENReplace that placeholder locally and ensure .env.local is ignored by Git. Bun supports the .npmrc scope/token syntax and environment substitution; see Bun’s configuration precedence . An overriding bunfig.toml, registry flag or registry environment setting can change which configuration is used.
Install only the packages your application needs:
bun add @preternatural-js/client-sdkFor administration, install @preternatural-js/admin-sdk instead. For an application-owned chat server, install @preternatural-js/self-hosted-app-server-sdk. See version availability before selecting a specific version. npm users can use npm install with the same .npmrc, but must supply the environment variable to npm themselves; npm does not load Bun’s dotenv files.
CI installation
Keep the scope mapping and variable reference in the project; put the token in the CI secret store. In GitHub Actions, the workflow’s GITHUB_TOKEN needs packages: read, and the workflow repository must have access to every private package it installs. A permission declaration alone does not grant another repository’s package access. Package owners configure that under Manage Actions access .
Pass the Actions token explicitly to the install step. For example, in a job that already checks out the project and installs Bun:
permissions:
contents: read
packages: read
steps:
# Checkout and Bun setup steps go before this step.
- name: Install dependencies
run: bun install --frozen-lockfile
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}This uses the existing lockfile and the project’s .npmrc. See GitHub Actions token authentication .
For other CI systems, provide a permitted classic token as GITHUB_TOKEN. Do not print it, expand it into logged commands or store it in build output.
Installation failures
| Result | Check |
|---|---|
401 or authentication error | The variable is present, the token has not expired, and the credential is configured for npm.pkg.github.com. |
403 or permission error | Token scope, account/package access, workflow repository access and any required organization authorization. |
404 or package/version not found | Scope mapping, exact package/version and read access; a hidden private package can look missing. |
| A private dependency fails | Read access must cover dependencies too, not only the package named in bun add. |
Do not post your .npmrc with resolved secrets or raw authenticated registry responses when reporting an install failure. Include the package/version, registry hostname and redacted error instead.