Agent and CI environments

A cloud agent session or a CI job runs Putnami with one secret, PUTNAMI_CLOUD_TOKEN, and no signed-in user. The token reads the remote build cache and writes nothing.

Use this recipe for an environment you configure yourself: a hosted coding agent, a CI service, or any machine where nobody runs putnami cloud login. Hosted Putnami CI needs none of it; see Hosted CI.

Allow the Putnami domains

An environment with a network allow list needs these hosts:

Host What calls it
putnami.dev The install script
put.putnami.dev The CLI and extension downloads that putnami.lock.json pins
npm.putnami.dev @putnami npm packages
go.putnami.dev go.putnami.dev/... Go modules
api.putnami.cloud putnami cloud commands that read the workspace
cache.putnami.cloud The remote build cache
storage.googleapis.com The files of a cache hit: the cache server answers with download links on this host

Each toolchain that putnami.lock.json pins names its download host in toolchains.<name>.source. Allow those hosts, and the registries your own dependencies come from.

Create the token

Run this once, on a machine where you are signed in:

putnami cloud token create --name <name> --scopes cache.read --expires 90d

The command prints the token, pkt_…, once. Store it as the environment variable PUTNAMI_CLOUD_TOKEN in the environment's settings. It is the only Putnami secret the environment needs. Do not put it in a setup script or in a tracked file.

The CLI reads the token from its own environment. A secret that the environment's network proxy adds to outgoing requests never reaches the CLI, so the cache then runs without a credential.

Create one token for each environment, and name it after that environment. You can then revoke one environment without touching the others.

A token belongs to the Cloud workspace you created it in. Run the command in a checkout of the repository the environment serves. Repositories linked to different workspaces need one environment and one token each.

To rotate the token, from a signed-in machine:

  1. Create a new token under a new name.
  2. Replace the PUTNAMI_CLOUD_TOKEN secret with the new value.
  3. Revoke the old token:
putnami cloud token revoke <name>

putnami cloud token status lists the tokens that expired or expire within 7 days.

Set up the environment

Add these lines to the environment's setup script:

curl -fsSL https://putnami.dev/install.sh | bash
putnami install

A repository that builds its own CLI sets cli.source to "workspace" in putnami.lock.json and holds ./putnamiw at its root. In that repository, run ./putnamiw install instead of putnami install.

The repository must be linked to a Cloud workspace: run putnami cloud setup once from a signed-in machine and commit the result.

Check the result

Run these commands in the environment:

putnami install
putnami lint,validate --impacted
putnami cloud cache status
Check Result
putnami cloud cache status The identity line reads workspace machine token from PUTNAMI_CLOUD_TOKEN, no signed-in user
A run the remote cache took part in The run summary prints a Remote cache: line with its hits and misses
A token the cache server refused The run prints an auth refused: line with source=cloud-env, and the tasks build locally

A token without the cache.read scope is refused with HTTP 403. Create a new token with --scopes cache.read.

When the cache uses the token

The build cache reads PUTNAMI_CLOUD_TOKEN only when all of these hold:

  • PUTNAMI_CACHE_TOKEN is not set. When it is set, it wins.
  • No user is signed in on the machine. A signed-in user keeps their own credential, so a token you export for another purpose never replaces it.
  • No hosted Putnami CI run started the build. A hosted run never sends PUTNAMI_CLOUD_TOKEN to the cache.
  • The cache config in .putnami/cache.json names no token source, or names putnami cloud token --for cache. A custom token command, a token URL, a metadata audience, and PUTNAMI_CACHE_TOKEN_SOURCE=metadata keep precedence.
  • The value is exactly one workspace machine token. A value with whitespace is refused, and the log line never shows the value.

Security

  • The token is read-only. It carries cache.read, with no cache.write and no deploy.* scope. The cache server refuses every write from a member's machine token, even one created with cache.write: only hosted CI writes to the shared cache.
  • The CLI keeps the token in memory. It does not write it to .putnami/cache.json or to a log.
  • In an agent session, repository code runs in the same environment as the token: a build, a test, or a script can read it. This is accepted for a read-only token. Do not give such an environment a token with more scopes.
  • Hosted Putnami CI runs do not use this token. The runner hands the run's credential to the published Putnami CLI that putnami.lock.json pins, and no task the run executes receives it. A repository that builds its own CLI with ./putnamiw differs: that CLI is repository code, and it holds the run's credential.

Next