Vercel Agent: shared registry credentials for private packages

A private package install can fail in a Vercel Agent session even when the same repository installs it during a Vercel build. The reason may be the credential scope: the agent reads team-shared environment variables, not project-scoped ones. For private packages on npm, Vercel says to use NPM_TOKEN; for custom or multiple registries, use NPM_RC. Add the variable for Development or Preview, then test the install using the repository’s normal package-manager command. The credential value stays outside the agent sandbox.

This matters when a production app depends on code your team cannot publish publicly: a paid UI package, an internal SDK, or a shared workspace library distributed through a private registry. A failed install can look like a lockfile or agent problem, when the actual issue is that the agent session cannot see the environment variable you configured at project scope. Fix the scope first; then check registry routing and package permissions if the install still fails. Vercel’s 30 September changelog entry describes the supported variables and the boundary around their values.

Start by identifying the registryCopy Anchor Link

Before changing settings, identify where the package is served. A package under a private npm organization may still be hosted at registry.npmjs.org; a company may instead use a custom registry, or route different scopes to different registries. The package name alone does not tell you which authentication file or token variable the repository expects.

Check the repository’s existing package-manager configuration and lockfile. Look for the registry URL associated with the package scope, and note whether the project uses npm, pnpm, or classic Yarn. Do not print token values while inspecting configuration. If a checked-in config refers to an environment variable, check the variable name only. If it contains a literal credential, stop and rotate it through the registry owner’s normal process before continuing.

The choice is small but consequential. Vercel’s instructions map private packages hosted on registry.npmjs.org to NPM_TOKEN. They map custom or multiple registries to NPM_RC, which configures registry behavior. Avoid setting both “just in case”: choose the variable that matches the package source and the repository’s current registry configuration. If the repository uses more than one registry, make sure its scope-to-registry mapping remains explicit so public packages do not get sent to a private endpoint by accident.

Put the value in the scope Vercel Agent readsCopy Anchor Link

Vercel Agent reads team-shared environment variables. Its changelog says it does not read project-scoped variables. This is the important distinction when a Vercel build succeeds but an agent session reports an authentication error: a variable attached to the project can be available to a build without being available to the agent session.

Create the appropriate shared variable for the team and select Development or Preview, as supported by the announcement. Use NPM_TOKEN for a private package hosted on the public npm registry, or NPM_RC for custom or multiple registries. Keep the token value in the environment-variable store. Do not paste it into an agent prompt, a chat transcript, a commit, or a config file that is meant to be checked in.

The announcement states that credential values stay outside the sandbox, so the agent cannot read them. That boundary is useful, but it does not make every token equally safe. Keep the token limited to the package access the workflow needs, use your organization’s established token rotation and access policies, and avoid granting publish rights when the task only needs installation. Those are operational precautions for your registry credentials, separate from the Vercel Agent behavior described in the release note.

Test the install without changing the lockfileCopy Anchor Link

Use a clean branch or a disposable worktree so the check cannot mix authentication changes with application edits. Confirm the expected variable name and environment selection with the team administrator, but never ask them to send the value in chat. After the shared variable has been saved, start a new Vercel Agent task or session so the test runs with the current team configuration.

Run the same install command the repository uses in its normal build. For example, use npm ci when the project is an npm project with a committed package-lock.json, or use the frozen-lockfile option already adopted by the pnpm or classic Yarn workflow. Do not switch package managers to make one experiment pass; doing that can change resolution behavior and obscure the actual problem. The changelog specifically names npm, pnpm, and classic Yarn as package managers that authenticate in agent sessions as they do in Vercel builds.

A useful check has three parts: the install exits successfully, the lockfile remains unchanged, and the package manager can resolve the private package from the expected registry. Record the package-manager version and the non-secret error output if the test fails. Never include the token, an authorization header, or a full environment dump in a build log or ticket. If installation still fails, verify the variable is team-shared rather than project-scoped, its target environment includes Development or Preview, and the registry configuration points the package scope to the host where it is actually published.

Separate credential failures from package failuresCopy Anchor Link

An authentication error usually points to scope, variable name, registry host, or token permissions. A not-found response can mean the package name or version is wrong, the requesting identity lacks read access, or the scope is routed to the wrong registry. A successful install followed by a type or build error is a different problem: the dependency was fetched, so return to the application’s compatibility and integration checks rather than rotating credentials at random.

Do not treat a successful Vercel build as proof that the agent will install the dependency, or a successful agent install as proof that production has access to it. They are separate execution contexts. The point of this configuration is to let the agent perform the dependency-install step with team-shared credentials while keeping credential values outside the sandbox. It does not remove the need to check the eventual deployment environment and its own access path.

This also fits a broader agent practice: keep an allowlist of the tools and packages a workflow may use, then verify a real task against that boundary. Our guide to pinning an agent skill allowlist covers the same kind of explicit control for installed skills. Here, apply the same discipline to registry hosts, package scopes, environment selection, and token privileges.

A short preflight before handing the task to an agentCopy Anchor Link

Before you ask an agent to install a private dependency, answer these questions:

1. Which package and exact version should the repository resolve?
2. Which registry serves that package scope?
3. Does the repository use npm, pnpm, or classic Yarn, and what install command does its build run?
4. Is the credential configured as a team-shared Development or Preview variable?
5. Is the variable name NPM_TOKEN for npmjs.org, or NPM_RC for custom or multiple registries?
6. Can you test a clean install without changing the lockfile or exposing the value?

If the answer to the fourth question is no, move the credential into the team-shared scope before diagnosing the application. If the install still fails after that change, preserve the exact non-secret error, registry host, package scope, and environment used. That evidence gives the registry administrator a concrete failure to investigate without widening access or leaking the credential.

SourcesCopy Anchor Link

• Vercel changelog: Vercel Agent now installs private packages from npm and custom registries