Registries

The platform runs four artifact registries, one per package ecosystem. Your tools publish to and pull from them with short-lived credentials scoped to you and one registry.

Registry Host Holds
put put.putnami.dev Putnami-native packages (config, migrations, archives, site content)
npm npm.putnami.dev npm packages
go go.putnami.dev Go modules
oci oci.putnami.dev OCI images

putnami cloud login links the workspace, records the registry endpoints, and writes each registry's token recipe (putnami cloud token --for <kind>). It mints no long-lived registry key.

Channels

A channel — canary, stable, pr-<n> — names one publication, and every registry answers it in its own protocol's native vocabulary:

Registry Ask for a channel with Answers with
npm the dist-tag in the packument, GET /<pkg> the version tagged canary
go GET /<module>/@v/<channel>.info {"Version": "…", "Time": "…"}
put download?channel=<channel> the archive on that channel
oci the image tag the manifest on that tag

The four answers name one publication. A publish stores an immutable release set, moves the channel to it, and the registries project that head onto their native tags, so @putnami/cli@canary and go.putnami.dev/http@canary resolve to the same release.

For Go this is the ordinary proxy protocol: the go command sends any query that is not a version as @v/<query>.info and then downloads the version that answered, so go get go.putnami.dev/http@canary works with no extra flags. GET /<module>/@latest?channel=<channel> returns the same answer.

A channel a package is not part of is absent, not stale: the dist-tag is missing from the packument and the Go proxy answers 404. A tool that reads a channel therefore never installs a version from an older publication by accident.

Reading a channel needs exactly the grant reading the version it names needs. A private package answers a channel the same way it answers a direct version request.

Consumer workspaces

A workspace that consumes another workspace's channel — putnami-cloud and foundry track the framework's canary — names that owner in its manifest so putnami upgrade --channel canary resolves the owner's release set, not its own:

{
  "options": {
    "@putnami/cloud": {
      "distribution": { "ownerWorkspace": "<owner workspace id>" }
    }
  }
}

Without the setting the linked workspace is the owner, which is right for the publishing workspace and wrong for every consumer. The consumer's users still need a read grant on the owner's release-set package and on each member they install; a lease the owner never granted is denied, not widened.

Private access

From a checkout linked to the owner workspace, activate each protocol namespace and grant another workspace read access to release history:

putnami cloud packages namespaces activate \
  --protocol npm --namespace @owner \
  --idempotency-key activate-owner-npm

putnami cloud packages grants create \
  --grantee-workspace-id <workspace-uuid> --channel latest \
  --idempotency-key latest-reader

The grant covers artifacts named through the selected release channel while the grant is active. Omit --channel to cover all release channels. Native registries resolve the exact artifact and the reader's workspace membership locally; a grant provides read access only. Internal artifacts remain confined to their owner workspace. Revocation also removes access to historical pins that depended on that grant, once the bounded authority refresh completes. A grant on a channel, or on all channels, that no other active grant of the owner covers takes effect at the next authority refresh, within about a minute.

Use putnami cloud packages namespaces list, putnami cloud packages grants list, and putnami cloud packages grants revoke <grant-id> for readback and revocation. putnami cloud packages status checks that the workspace binds each namespace your checkout needs. The linked checkout fixes the owner; creator and namespace authority are server-derived. The command calls Put directly with your native registry credential. Only an authorized human workspace administrator can create or revoke a grant. Package/action, principal-kind and migration-purpose flags belong to the retired grant contract and are refused.

A namespace has one owner workspace. Another workspace publishes into it through package shares: the owner shares one exact package with it, as reader or publisher, with POST /v1/workspaces/<owner>/distribution/package-shares. GET /v1/workspaces/<workspace>/distribution/package-shares/received lists the shares your workspace holds, revoked ones included. A share drops out of the list when its owner moves the namespace to a new binding, because the registries stop honoring it. It names the package and the permission, not the owner workspace. Such a workspace cannot bind the owner's namespace, so putnami cloud packages status and the oci-binding row of putnami cloud env doctor pass with no OCI binding when the workspace holds at least one active OCI publisher share.

Credentials

Want to… Do this
Set up / show registry endpoints putnami cloud registries
Manage owner bindings and grants putnami cloud packages
Get a registry bearer putnami cloud token --for npm|go|oci|put
Get one by host instead putnami cloud registry-token --host <host>
Materialize for one native invocation Add --materialize (the bearer is not printed)
Revoke and remove tokens putnami cloud logout

A registry token is issued for you and one registry. That is the whole input: there is no owner workspace, package, or action to pass, and passing one is an error rather than a silent no-op.

What the token can reach is decided by the registry, not by the token. For each namespace you touch, the registry finds the workspace that owns it and asks IAM whether you are a member with read or publish there. So access follows workspace membership and team grants — where it is administered — and it changes the moment membership changes, without reissuing anything. A publish that also writes a channel tag needs no second credential: whoever may publish into a namespace may tag within it.

Tokens are short-lived and cached locally until shortly before they expire, so a publish that resolves the recipe once per package does not mint once per package.

npm, netrc, and Docker credential files are host-keyed, which now matches the credential: one bearer per host, good for everything you may reach there. --materialize writes it for one immediate invocation.

--materialize writes to the credential files native tools actually read — $HOME/.npmrc for --for npm and $HOME/.netrc for --for go — never under PUTNAMI_HOME, even when a wrapper (such as the framework CLI launching an extension) sets PUTNAMI_HOME to a different directory.

Install through the credential provider

If your Putnami CLI lists --providers in putnami --help, a build can ask @putnami/cloud for its registry read credential instead of the per-registry files:

putnami build --providers install

PUTNAMI_PROVIDERS=install turns it on for every command in that shell. Without either, nothing changes.

The provider mints one short-lived bearer for you, for the hosts of the four registry endpoints (go, npm, oci and put). It needs two things:

  1. You are signed in with putnami cloud login.
  2. The checkout is linked with putnami cloud setup.

Otherwise the provider answers that it holds no credential, and the CLI keeps the credentials your native tools already have. As with cloud token, each registry decides per namespace what the bearer may read. The bearer is cached with the other registry tokens until shortly before it expires, and putnami cloud logout removes it. The provider never answers a publish credential: publishing keeps using putnami cloud token.

Publishing

Most publishing happens as part of putnami publish. The Putnami-native (put) registry also has direct publishers:

Publish… Command
Config schema + values putnami cloud config publish
Migration bundle putnami cloud db migrations publish
Pre-built archives putnami cloud packages publish

OCI images

The OCI registry can copy and retag images server-side, without pulling and re-pushing layers:

Want to… Do this
Copy an image between repos putnami cloud packages copy <src-ref> <dst-ref>
Add tags to an existing digest putnami cloud packages retag <ref> <tag…>
Roll a tag back to its previous image putnami cloud packages revert <repo>:<tag>

Refs are registry-relative (ns/name, ns/name:tag, or ns/name@sha256:…). Both verbs are pure metadata within the shared content-addressed store — zero blob bytes move — and a multi-arch image index is copied whole (every platform manifest comes along). Credentials come from the registry token seam (the same one cloud login provisions), never from provider credentials.

Availability

Page Status
Putnami packages (put) Planned
npm registry Planned
Go module proxy Planned
OCI images Available: copy and retag are documented above

Next