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-readerThe 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 installPUTNAMI_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:
- You are signed in with
putnami cloud login. - 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 |