143 docs
Guides

Private npm packages

Install private npm dependencies with repository credentials kept outside coding-agent environments.

Use this setup when a repository depends on private, scoped npm packages. You need an organization administrator to save a read-only registry token and permission to commit the repository configuration.

Add a registry credential

  1. Open Settings → Package registries under Runtime.
  2. Select the repository, then choose Add credential.
  3. Enter the registry's HTTPS origin, an explicit lowercase npm scope, and a read-only package token.

For example, use https://registry.example.test with @example. The registry must use a DNS hostname on HTTPS port 443, without a path, query, fragment, or embedded credentials. Each repository can have one credential per registry origin and one per package scope. Distinct registry origins are supported.

Scope the token to the packages this repository needs. Tokens cannot be revealed after saving. Use Rotate to replace a token for the same registry and scope. To change the registry or scope, delete the credential and create a new one. Deleting a credential affects future dependency installation; it does not remove dependencies already installed in a workspace.

Declare controlled installation

Commit .143/config.json with the npm directories that require installation:

{
  "setup": {
    "npm": [
      { "directory": "." },
      { "directory": "tools/example", "legacy_peer_deps": true }
    ]
  },
  "bootstrap": {
    "commands": ["npm rebuild", "npm run build"]
  },
  "validation": {
    "commands": ["npm test", "npm run lint"]
  }
}

Each directory needs a committed package.json and npm lockfile version 2 or 3 in package-lock.json. Paths are relative to the repository root. . selects the root project. For an npm workspace, select the workspace root so its lockfile controls the installation. A standalone nested project, such as tools/example, needs its own manifest and lockfile. List the root installation first when a nested project relies on peers provided by the root. Use legacy_peer_deps: true only when that project's lockfile requires npm's legacy peer-dependency resolution.

143 runs a platform-controlled npm ci --ignore-scripts --no-audit before repository bootstrap in coding sessions and automations. It uses the saved credential only during this installation. Package lifecycle scripts are skipped while credentials are available. The isolated installer uses the typed legacy_peer_deps field in place of repository .npmrc settings.

If dependencies need lifecycle scripts, run npm rebuild or the specific required script in your bootstrap or review commands afterward. These commands run after credential removal. Remove duplicate npm ci commands from those recipes because reinstalling discards the dependencies already prepared and needs a registry token.

Opt in to installation for built-in reviews

Built-in code reviews inspect the checked-out source by default. If reviewers need npm dependencies to run tests or other checks, set review.install_npm_dependencies to true alongside the existing setup.npm directories in .143/config.json.

{
  "setup": {
    "npm": [{ "directory": "." }]
  },
  "review": {
    "install_npm_dependencies": true
  }
}

This setting enables the isolated installer during built-in review preparation. Existing setup.npm declarations continue to drive installation for coding sessions and automations.

Node and npm versions

Controlled installation selects a toolchain that satisfies the repository's .nvmrc, .node-version, and package.json declarations (engines.node, engines.npm, and an npm packageManager pin). Declarations in the repository root and each configured npm directory must agree. Exact version pins are respected; conflicting requirements or unavailable versions stop setup with a runtime compatibility error.

The sandbox image includes these pinned toolchains:

Nodenpm
24.22.211.19.1
22.23.410.9.9

When both toolchains satisfy the declarations, or none are present, Node 24 is selected. Version files must be regular files and support numeric full versions, majors, and minor versions; engines supports version ranges. Symlinks and moving aliases such as lts/* are not supported. Instance administrators can add supported versions to the image's toolchain catalog and rebuild the sandbox image.

The selected versions are also used by subsequent repository bootstrap commands. Changing toolchains invalidates cached npm dependency setup. Toolchains are installed and checksum-verified when the image is built; repository setup does not download or execute a repository-provided package manager while registry credentials are available. Installation remains npm ci and does not rewrite the committed lockfile.

Credential boundaries

Package credentials belong to the selected repository. They are not injected as environment variables, exposed to coding agents, or available to arbitrary repository scripts. Preview applications and preview secret bundles use their existing configuration separately.

Authenticated setup requires a trusted repository configuration. Reviews from forks or with unknown source trust cannot use repository package credentials. Setup supports scoped npm packages downloaded over HTTPS and npm workspace links. A configured npm target can declare a file: dependency on a package directory under any configured target. The lockfile must link to that same directory, and only the package manifest is staged for installation. Git, SSH, HTTP, local tarballs, and direct tarball URL dependency specifications are rejected. Other package managers and registry credentials are not supported.

Troubleshooting

  • An opted-in review reports an npm setup failure. Check that the declared Node and npm versions match a supported toolchain, then validate the committed lockfile with those versions. Fix the inputs and request a new review. Recognized deterministic npm failures stop the review before launching reviewers. Transient failures retain bounded retries. Instance administrators can inspect the sanitized error code, Node/npm versions, and installation duration.
  • Authentication fails: check that the registry origin and package scope match the locked packages, and rotate an expired or insufficiently scoped token.
  • A package needs an install script: add the required script to bootstrap or review commands after controlled installation. Do not put the token in those commands.
  • Credential storage is unavailable: ask your instance administrator to configure package credential encryption, then try again. 143 does not save plaintext tokens as a fallback.
  • A credential changed while you edited it: refresh the page before rotating or deleting again.

Keep tokens out of .143/config.json, .npmrc, repository history, session messages, and preview secret bundles used as a substitute for package setup.

On this page