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 distribution bindings activate \
  --protocol npm --namespace @owner \
  --idempotency-key activate-owner-npm

putnami cloud distribution 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.

Use distribution bindings list, distribution grants list, and distribution grants revoke <grant-id> for readback and revocation. 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.

Credentials

Want to…	Do this
Set up / show registry endpoints	putnami cloud registries
Manage owner bindings and grants	putnami cloud distribution
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.

Publishing

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

Publish…	Command
Config schema + values	putnami cloud publish-config
Migration bundle	putnami cloud publish-migration
Pre-built archives	putnami cloud publish-archives
Docs (site-content bundle)	putnami cloud publish-doc

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 oci copy <src-ref> <dst-ref>
Add tags to an existing digest	putnami cloud oci retag <ref> <tag…>
Roll a tag back to its previous image	putnami cloud oci 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

• Log in
• CLI reference