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.
Link the repository
putnami cloud setupWith 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 --autoVerify
putnami cloud config --schema # the resolved config schema for a project
putnami cloud whoami # the active identity