Set up the workspace

putnami cloud setup links this repository to a Putnami Cloud workspace and provisions the workspace-local config the platform needs. Run it once per repository.

Deploying needs to know which Cloud workspace to deploy into. Setup records that link in your manifest (safe to commit) and, at the same time, turns on the remote build cache and registry credentials.

putnami cloud setup

With no arguments, setup creates a new workspace (named from your putnami.workspace.json / putnami.json name) and links it. To link an existing workspace instead, pass its id:

putnami cloud setup --workspace <workspace-id>
Want to… Do this
Link an existing workspace putnami cloud setup --workspace <id>
Name a new workspace putnami cloud setup --workspace-name "<name>"
Choose the slug of a new workspace putnami cloud setup --slug <slug>
Target a non-default environment putnami cloud setup --environment <env>
Skip the build cache putnami cloud setup --no-cache
Enable Intelligence putnami intelligence setup
Disable Intelligence putnami intelligence setup --disable
Override the Intelligence graph slug putnami intelligence setup --graph <slug>
Record the repository URL putnami cloud setup --repository <url>

Choose the slug of a new workspace

A slug is the short name of a workspace, such as acme. The platform uses it to name what the workspace runs: its services start with <slug>-, and the workspace holds the event topic names that start with <slug>., such as acme.orders.created.

putnami cloud setup --workspace-name "Acme" --slug acme
Rule Detail
Length at most 12 characters
Characters lowercase letters, digits and single dashes, starting with a letter: acme, acme-prod, a1
Unique no two workspaces share a slug; setup fails when the slug is taken
Fixed a workspace keeps the slug it was created with
Refused names the platform's own names: business, catalog, cloud, config, control, data, delivery, distribution, events, identity, infra, intelligence, observability, platform, putnami, qa, runtime, source, surfaces, tooling
Refused endings a dash and one of those names, such as my-data or api-identity: the platform refuses every push receive of a topic named under such a slug

Setup checks the slug before it sends any request. Without --slug, the platform derives a slug from the workspace id, such as w-0-db8055e0. It is valid, and hard to read: choose a slug when you create the workspace.

--slug applies only when setup creates the workspace. When the repository is already linked, or with --workspace, setup accepts the flag only when it is the workspace's slug, so you can run the same command twice. With another slug, setup stops and writes nothing in the repository.

The name is not fixed. An admin of the workspace renames it in putnami.app, under Workspaces in the avatar menu, and every member reads the new name. The slug and the workspace's addresses do not change. On the same page, each person hides the workspaces they do not use from their own list.

Add people to the workspace

An admin of the workspace adds people in putnami.app, under Members in the avatar menu. Each person gets one role:

Role What it allows
workspace.viewer read runs, verdicts and changes, and change nothing
workspace.member also run work on Putnami Cloud
workspace.admin also manage the workspace, its members, its configuration and its secrets

There are two ways to add someone:

Way How it works
By email Enter their email address and a role. They sign in with that address.
With a link Pick a role and select Create link, then send the link yourself. Putnami sends no email.

An invitation link:

  • shows once, when you create it: copy it then;
  • lets one person join, once;
  • expires after 7 days;
  • stops working when an admin revokes it under Pending links, or when the person who created it is no longer an admin of the workspace.

A workspace holds at most 100 pending links. Revoke one to create another.

The person opens the link and signs in. The page then says which workspace and role the link offers, and when it expires. They select Accept and join and land in the workspace with the link's role. A link that was used, expired or revoked says so; ask an admin for a new one.

What setup writes

File Purpose Commit it?
putnami.workspace.json → options.@putnami/cloud.workspace the workspace id (and control-plane URL if non-default) yes
putnami.workspace.json → options.@putnami/intelligence explicit Intelligence enablement and graph workspace slug, written by putnami intelligence setup yes
.putnami/cache.json remote build cache config — a token source, never a raw bearer yes
.putnami/cloud-link.json local mirror of the link no (local cache)

The committed link is intentionally minimal: just enough to connect the repository to its workspace. Everything else is resolved from the control plane at use time.

putnami cloud setup writes only the link and the cache settings. Intelligence is the @putnami/intelligence extension's concern: run putnami intelligence setup after linking. Intelligence reads its settings from options.@putnami/intelligence only. A repository that still holds the retired options.@putnami/cloud.intelligence block must move its fields there: Intelligence ignores the old block.

Opting out records a disabled feature flag and never deletes wiring installed by an earlier setup. The /audit skill is not written by setup: it ships as agent content of the @putnami/intelligence extension. Add extension:@putnami/intelligence to agentArtifacts and run putnami install to materialize it. A repository set up before this change holds an older copy under .AI/skills/audit, .agents/skills/audit and .claude/skills/audit, listed in .AI/skills/audit/.putnami-managed.json. Delete those three directories first: putnami install preserves files it does not manage, so the old skill would stay in place.

Hosted Intelligence availability

putnami intelligence setup discovers whether hosted Putnami Intelligence may be used: it reads the linked workspace's product-subscription status and reports one of

Outcome What it means
available the subscription is active, entitled, and activated — Source's code index answers
not_subscribed the workspace has no Intelligence subscription, or canceled it; a workspace administrator subscribes it
suspended the subscription is suspended; contact Putnami support
not_entitled the subscription is active but its entitlement is currently withheld
activating entitled, with activation still being prepared — wait, nothing is wrong
unavailable availability could not be confirmed (offline, expired session, control plane unreachable)

The recorded options.@putnami/intelligence.enabled flag is a repository opt-out, not an entitlement: --disable turns the local wiring off (and skips the discovery call entirely), while an enabled repository still has to clear discovery on every hosted call. --graph and the PUTNAMI_INTELLIGENCE_URL / PUTNAMI_INTELLIGENCE_WORKSPACE / PUTNAMI_INTELLIGENCE_AUDIENCE environment overrides likewise only change where an available product is reached — they can never make an unsubscribed workspace report available, and a control plane that cannot answer blocks rather than falling back to enabled.

A fail-closed outcome never fails setup and never removes wiring: the tools re-discover on each call, so a subscription added later needs no second setup run. Subscribing and cancelling are workspace-administration actions on the control plane — the CLI has no subscription commands.

Tuning the discovery call

Discovery fronts every hosted tool call, so two local knobs bound what it costs. Both accept a Go duration (45s, 2m) or a plain number of seconds, and both sit under options.@putnami/intelligence.discovery in the workspace manifest, with an environment override:

Setting Env override Default Meaning
timeout PUTNAMI_INTELLIGENCE_DISCOVERY_TIMEOUT 5s how long the composed read may take before availability counts as unconfirmed. Raise it when the control plane is cold-starting and the first call of a session reports unavailable on an entitled workspace.
cacheTtl PUTNAMI_INTELLIGENCE_DISCOVERY_TTL 60s how long an available answer is reused from ~/.putnami/cache/intelligence/discovery. 0 disables the cache; values above 10m are clamped.

Only available is ever cached, keyed by control plane, workspace, and credential — a deny, a suspension, an activation in flight, or an unreachable control plane is always re-asked, and a revocation lands at the next expiry. Neither knob can make an unsubscribed workspace report available.

Ensure mode for automation

--auto makes setup idempotent and non-failing: it configures Cloud only when the repository is already linked and you are already signed in, never creates a workspace, and never breaks the surrounding command. This is the mode the extension's install hook uses.

putnami cloud setup --auto

Verify

putnami cloud config --schema     # the resolved config schema for a project
putnami cloud whoami              # the active identity

Next