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 and installs the managed Putnami Intelligence MCP and portable audit workflow.

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>"
Target a non-default environment putnami cloud setup --environment <env>
Skip the build cache putnami cloud setup --no-cache
Disable Intelligence and audit putnami cloud setup --no-intelligence
Keep Intelligence but disable audit putnami cloud setup --no-audit
Override the Intelligence graph slug putnami cloud setup --intelligence-workspace <slug>
Adopt a conflicting audit workflow putnami cloud setup --force-audit
Record the repository URL putnami cloud setup --repository <url>

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/cloud.intelligence explicit Intelligence/audit enablement and graph workspace slug yes
.AI/skills/audit, .agents/skills/audit, .claude/skills/audit managed portable audit workflow and agent adapters yes
.mcp.json, .codex/config.toml shared putnami mcp wiring (run_jobs remains prompted); Codex uses ./putnamiw when the workspace ships the wrapper and requires the server to initialize yes
.AI/domains.json deterministic project-domain grouping, only generated when absent 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.

Setup requires a freshly logged-in session carrying intelligence.audit before it changes repository files. If an older session lacks the scope, rerun putnami cloud login. Opting out records disabled feature flags and never deletes workflow files installed by an earlier setup.

Hosted Intelligence availability

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 — the hosted MCP tools answer
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/cloud.intelligence.enabled flag is a repository opt-out, not an entitlement: --no-intelligence turns the local wiring off (and skips the discovery call entirely), while an enabled repository still has to clear discovery on every hosted call. --intelligence-workspace 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/cloud.intelligence.discovery in the recorded Cloud link, 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