Skip to content

Package Registry

Canopy Host includes an npm-protocol registry. It is a real registry, not a proxy: npm, bun, pnpm and Changesets all talk to it unmodified, because it speaks the npm protocol rather than a Canopy-specific one.

The npm registry and registry namespace management use the host.registry platform feature. It is GA, public and enabled by default, and teams can disable it. The content-addressed artifact blob store described below is a separate API surface gated by host.releases.

A package lives under a scope (@acme/widgets). A scope is registered to a team as a registry namespace, and a team can hold several.

canopy registry namespace create @acme --team <team_id>

Registering a scope is enough to publish into it. Verifying it (a DNS TXT record at _canopy-registry.<your-domain>) is optional and separate: it attaches a provenance attestation to every publish and is what the “verified” badge asserts.

canopy registry namespace verify <namespace_id> --team <team_id> --domain acme.com
canopy registry namespace status <namespace_id> --team <team_id>

Then point your project’s npm client at Canopy:

canopy registry login --scope @acme

That writes a managed block into ./.npmrc:

# >>> canopy registry (managed by `canopy registry login`) >>>
@acme:registry=https://api.canopy.pm/registry/npm/
//api.canopy.pm/registry/npm/:_authToken=chy_...
# <<< canopy registry <<<

Re-running login rewrites that block rather than appending a second copy, so rotating your API key works by just running it again. Anything else in your .npmrc is left untouched.

Check connectivity the ordinary way:

npm ping --registry https://api.canopy.pm/registry/npm/
npm whoami --registry https://api.canopy.pm/registry/npm/

There is no Canopy-specific publish tool, and you don’t need one. Once .npmrc is configured, the standard workflow works:

npm version patch # or minor / major - rewrites package.json, tags git
npm publish # or: bun publish

canopy registry publish exists as a shortcut for the last step. It really does shell out to npm publish - it just refuses to run when no scoped registry is configured, so a private package can’t leak to registry.npmjs.org by accident:

canopy registry publish [--tag <tag>] [--dry-run]

Publishing a version that already exists is a 409, always. There is no unpublish and no overwrite - a published version stays exactly as published, forever. If you shipped a mistake, publish a new version.

This is stricter than npmjs.com (which allows an unpublish within 72 hours) and deliberately so: anything installed from this registry can be cached and depended on, and a mutable version is a supply-chain hazard.

A publish may carry a _canopy object next to versions and _attachments; npm clients never send one. It is sent by a package build environment (see Canopy Pipelines) and holds build_id, source_commit, bump (major, minor or patch), change_files, changelog_md and release_files (write: a list of path and content, delete: a list of paths, all relative to the repository root). The registry answers 422 when the build does not belong to the team that owns the scope or a release file path is absolute or leaves the repository, and otherwise links the published artifact to the build and commit and keeps a release record for the version.

A plain npm publish moves the latest tag. To ship a prerelease that doesn’t:

npm publish --tag next

To promote an already-published version to latest later - or to manage any other tag:

npm dist-tag add @acme/widgets@2.0.0 latest
npm dist-tag ls @acme/widgets
npm dist-tag rm @acme/widgets next

The same operations are available from the Canopy CLI, which is handy on a machine that is logged into canopy but has no .npmrc:

canopy registry dist-tag ls <@scope/name>
canopy registry dist-tag add <@scope/name@version> <tag>
canopy registry dist-tag rm <@scope/name> <tag>

latest can never be removed - every package must always have one, or a bare npm install would have nothing to resolve.

The very first version ever published for a package always becomes latest, even under --tag next, since there is nothing else for latest to point at yet.

canopy registry info <@scope/name> # every dist-tag and version
canopy registry stats <@scope/name> # pull counts by version
canopy registry daily-pulls <@scope/name> <version> [--since-days <n>]

npm view @acme/widgets works too.

By default every scope is private: installing from it requires a Canopy API key of a member of the team that owns the scope (any role, the owner included). A key of any other account gets a 404, the same answer as for a scope that does not exist, and a request with no key gets a 401. A key pinned to one team (a Space-scoped key) acts on that team’s scopes only, on every npm route: reading a private scope, publishing, dist-tags, deprecating and yanking all answer 404 for a scope of another team, even when the key’s owner is a member of both teams. A CI job can install from a private scope when its repository is allowed on the namespace, and an agent identity can when it belongs to the owning team.

A scope can be made public, which means anyone can install packages under it with no Canopy account and no credential at all - the way you’d ship an SDK or CLI to your own customers.

canopy registry namespace public <namespace_id> --team <team_id>
canopy registry namespace public <namespace_id> --team <team_id> --private

Or from the dashboard: Teams → Registry, then the Make public / Make private button next to the scope.

Visibility is per scope, not per package - the same boundary npmjs.com’s --access public, GitLab’s project visibility and GitHub Packages’ repository visibility use. Making @acme public makes everything under it installable, which avoids the failure mode where one forgotten package in an otherwise-public scope silently 401s a customer.

What “public” does and does not change:

private scope public scope
npm install (packument, tarball, dist-tag reads) API key of a member of the owning team no credential needed
npm publish, npm dist-tag add/rm API key + registry:publish API key + registry:publish
Pull counts / analytics API key of a member of the owning team API key required

Changing visibility is gated on registry:admin (the same permission as registering and verifying a scope), not registry:publish - exposing a scope to the internet is an org-level decision, not something a publishing job should be able to flip.

Your users need one line of config and nothing else:

npm config set @acme:registry https://api.canopy.pm/registry/npm/
npm install @acme/widgets

or, in their project’s .npmrc:

@acme:registry=https://api.canopy.pm/registry/npm/

A key created with operation_scope: registry:read reads /registry (packuments, tarballs and, as they arrive, the Python and Go indexes) and nothing else: it cannot publish, deprecate or delete, and it reaches no other route. It is the right credential for a machine that only installs private packages. Like every key it can be pinned to one team, in which case a private package of another team answers 404, the same answer as for a package that does not exist.

The same team namespaces also own Docker images at registry.canopy.pm. The first path component of an image name is the namespace (without the @), so @acme owns registry.canopy.pm/acme/....

canopy images login --team <team_id>
docker build -t registry.canopy.pm/acme/build-tools:1 .
docker push registry.canopy.pm/acme/build-tools:1

canopy images login creates a dedicated API key with the images:write scope (or images:read with --read-only, for a machine that only pulls) and runs docker login registry.canopy.pm with your email and that key. The key only works against the registry: it cannot reach the rest of the API, and a general-purpose key is refused by the registry. --team pins it to one team. You can also do it by hand: create a key with operation_scope: images:write and docker login registry.canopy.pm -u <your email> with the key as the password.

Pushing needs the registry:publish role on the namespace’s team; pulling needs team read access. Nothing outside your namespaces is reachable.

canopy images list --team <team_id>

The dashboard shows the same under Images (tags with their size, layer count, platform and build time, read from the registry itself).

Each step() in canopy.pipeline.ts takes its own image, so different steps can run in different images (an SDK-drift step in one, the API tests in another). Pin it by digest:

step('test', {
image: 'registry.canopy.pm/acme/build-tools@sha256:<digest>',
run: 'bun test',
inputs: [src],
});

canopy images pin acme/build-tools:1 --team <team_id> resolves a tag you pushed to that digest-pinned reference and prints the line to paste. The dashboard’s Images page has the same as copy buttons (digest, image ref, or the ready-made image: line).

A step’s identity stays content-addressed, so the pipeline itself only ever runs a digest. To write a tag instead, lock it:

step('test', { image: 'registry.canopy.pm/acme/build-tools:1', run: 'bun test', inputs: [src] });
canopy images lock canopy.pipeline.ts --team <team_id> # writes canopy.images.lock next to it - commit it

The lock records the digest the tag points at, and Canopy swaps the tag for that digest before validating, so the same commit always runs the same image. The lock only moves when you ask (--update); --check fails in CI if the lock is missing an entry or a tag has moved on. A tag with no lock entry is an error that names the step. Only tags on registry.canopy.pm are locked this way; canopy pipelines check applies the lock offline too. The team must own the namespace. The first time a pipeline needs the image on a build Grove, Canopy copies it there, so the digest stays identical everywhere. Bake your dependencies into the image once and the steps stop reinstalling them on every run.

Artifact blobs are part of the Host artifact API, not the npm registry. The /artifacts routes are gated by host.releases (also GA, public and enabled by default). Uploading still requires the team’s registry:publish action; listing and downloading require environment:read.

Model weights, datasets, checkpoints and native bundles are not container images, so they do not live in the Docker registry. They go into a content-addressed blob store, and each blob is registered as an artifact of your team (storage_kind artifact_store, type native-bundle, model, dataset or checkpoint).

canopy artifacts blob put ./llama.gguf --team <team_id> --type model --name llama-3
canopy artifacts blob ls --team <team_id> [--type model]
canopy artifacts blob get sha256:<hex> --team <team_id> --out ./llama.gguf

blob put hashes the file locally, skips the upload if your team already holds the same bytes, and otherwise streams it to the API with a Content-Length. The server hashes the body as it arrives and rejects it with a 400 (blob_digest_mismatch) unless the sha256 equals the digest you declared; nothing is stored in that case. blob get verifies the digest as it writes and removes the file if the bytes do not match.

Behaviour worth knowing:

  • Uploading the same bytes twice is idempotent: the second call answers 200 with the existing artifact instead of 201.
  • A blob is visible only to teams that registered it. Another team’s blob with the same digest answers 404.
  • Uploads need the registry:publish action on the team; reading and listing need only team membership.
  • Empty bodies are refused, and a body larger than the configured maximum (ARTIFACT_STORE_MAX_BYTES, 5 GiB by default) answers 413.
  • A blob is deleted only when no artifact references it and it is older than a grace period (ARTIFACT_STORE_GC_GRACE_HOURS, 24 hours by default). An hourly job removes unreferenced blobs and abandoned partial uploads, a bounded batch at a time.
Method Path
POST /artifacts/blobs?team_id=&type=&digest=sha256:<hex>[&name=&media_type=&platform=]
GET /artifacts/blobs?team_id=[&type=]
GET | HEAD /artifacts/blobs/{digest}?team_id=

The digest of an upload may be sent in the X-Canopy-Digest header instead of the query string. Chunked uploads are refused with 411; send a Content-Length.

The routes are the standard npm ones, under /registry/npm/. Package specs are accepted both percent-encoded as a single segment (@acme%2fwidgets, what real npm/bun clients send) and as two path segments. Current npm API limits are enforced per API process: anonymous reads are limited to 60 per minute per IP, authenticated reads to 300 per minute per principal, and writes to 20 per minute per IP. A 429 response means the caller should retry later.

Method Path
GET /registry/npm/-/ping
GET /registry/npm/-/whoami
GET /registry/npm/-/public-packages
GET | PUT /registry/npm/{spec}
GET /registry/npm/{spec}/-/{filename}
GET /registry/npm/-/package/{spec}/dist-tags
PUT | DELETE /registry/npm/-/package/{spec}/dist-tags/{tag}
PUT | DELETE /registry/npm/-/package/{scope}/{name}/dist-tags/{tag}
GET /registry/npm/{scope}/{name}/stats
GET /registry/npm/{scope}/{name}/releases
GET /registry/npm/{scope}/{name}/{version}/pulls-daily
PUT /registry/npm/{scope}/{name}/{version}/deprecate
PUT | DELETE /registry/npm/{scope}/{name}/{version}/yank
GET | POST /teams/{team_id}/registry-namespaces
GET | PATCH /teams/{team_id}/registry-namespaces/{namespace_id}
POST /teams/{team_id}/registry-namespaces/{namespace_id}/verify
GET | POST /teams/{team_id}/registry-namespaces/{namespace_id}/repositories
DELETE /teams/{team_id}/registry-namespaces/{namespace_id}/repositories/{grant_id}

The CLI also exposes version lifecycle actions:

Terminal window
canopy registry deprecate @acme/widgets@1.0.0 'Use 2.x instead'
canopy registry yank @acme/widgets@1.0.0 'Compromised release' --severity security
canopy registry unyank @acme/widgets@1.0.0

Deprecation leaves the version installable but asks npm-compatible clients to warn. A yank removes the version from dist-tags but does not remove its tarball. A security yank also blocks Canopy’s plugin resolver and pipeline generator from newly resolving or generating against that version. A housekeeping yank does not apply that stronger block.

Full schemas: API Reference.