Every private dependency creates the same small crisis. The build needs a registry token, and the three usual answers are all bad: commit an .npmrc, paste the token into an environment variable that then lives in the running container forever, or give up and vendor the package.
Build secrets are the fourth answer. Values are encrypted separately from your deployment, delivered only to the agent that is building, mounted only while the build runs, and removed afterwards.
What you get
- Encrypted at rest, bound to your account, the agent and the application
- Names only in reviews: the portal, the API and MCP show
build_secret_names, never values - Build time only: a secret never becomes a runtime environment variable
- Removed after the build, along with its temporary files
- Never inherited by previews, so a review branch does not silently gain your registry access
How a value reaches the build
For the generated npm recipes, the reserved name npmrc supplies an npm configuration file during dependency installation only. That is where a registry token belongs. Scope it to its registry host rather than issuing a token that works everywhere.
Any other name is mounted at /run/secrets/NAME, and only while build scripts run. For a Dockerfile build you request each secret explicitly with a mount, so nothing appears unless your own build asks for it.
The package managers each have their own file. pnpm takes build_secrets.npmrc. Yarn takes build_secrets.yarnrc with YAML configuration, mounted at /app/.yarnrc.yml for installation only. Sending the wrong one for your manager is refused rather than silently ignored.
Set it up
Check the agent
Build credentials need agent 0.6.11 or later advertising build secret support, and local MCP 0.34.0 or later when you use the local connector. An agent without it refuses the deployment before receiving any command, which is the correct order: no credential is sent to something that cannot handle it.
Issue a scoped token
Create a registry token limited to the packages and the host you actually need. This is the control that still protects you if everything else fails.
Supply it as a build secret
In My Apps, use Build secrets; over the API or MCP, send build_secrets as a JSON object. Names start with a letter and hold ASCII letters, digits and underscores, up to 64 characters. Up to 16 values, 64 KB each, 256 KB in total.
Deploy and read the review
The review and the deployment record list the names you sent, and nothing else. Manifests and queued jobs carry names and temporary file references, not values.
Rotate on a schedule you choose
Rotation is its own operation: send a new set of values for the deployment. Rotate when someone leaves, when a token ages, and immediately if a build log ever surprises you.
public_build_vars exists for values that belong in a browser bundle, and anything placed there can appear in the bundle and in image metadata. It is the wrong home for a registry token, and the platform does not stop you from making that mistake. Credentials go in build secrets, which are a separate input with separate rules.
The assigned agent obtains values only for its active authorized operation, files are private to the agent state, and build output is withheld from you rather than streamed back. What none of that can prevent is a build script that deliberately prints its own secret, or a dependency that exfiltrates one. Use trusted project code. If an operation is interrupted, it still needs recovery verification before anything can be called clean.
A branch preview never inherits build secrets automatically. If a preview genuinely needs registry access, it has to be given it on purpose. That default is what keeps a temporary environment built from a feature branch from quietly holding your production registry token.
Where this fits
Private dependencies are only one reason to use the generated recipes at all. If the rest of your build needs system packages, a compiler or a custom base image, write a Dockerfile and request the secrets explicitly there.
For a private repository rather than a private package, that is a different mechanism entirely: see deploying from a private Git repo.
Start now
Get an offshore VPS with the agent preselected, then set up the build: Node server, static site or one app from a monorepo.