Workspace contracts

Each workspace file owns one part of the delivery contract. Keeping runtime, resources, configuration, and automation separate makes a change reviewable before it reaches Cloud.

Use this page when you need to decide where a new setting belongs or which validation proves it.

Find the owning file

File Owns
putnami.workspace.json Workspace-wide extensions, registries, and the committed Cloud workspace link
<project>/putnami.json Project identity, dependencies, capabilities, and publishable artifact kinds
<project>/infra/runtime.json Whether a workload is deployable, plus ingress, scaling, resources, and runtime security
<project>/infra/requirements.json Named databases, storage, events, and secret requirements that Cloud resolves into bindings
<project>/schema/config.json The shape, types, and visibility of application configuration
<project>/conf/env.<env>.yaml Non-secret authored values for one environment
putnami.ci.json Hosted CI commands, runner policy, publication channels, trigger rules, and followed environments

Secrets never belong in conf/env.<env>.yaml or a committed manifest. Declare the requirement, then write the value through putnami cloud secrets.

Make a service deployable

The presence of infra/runtime.json makes a project deployable. This minimal declaration exposes one domain and allows the service to scale to zero:

{
  "ingress": { "domains": ["hello.example.com"] },
  "scaling": { "max": 2, "concurrency": 500 }
}

Add infra/requirements.json only when the service consumes a managed resource. The logical names in that file are application-facing identities; provider resource names and credentials stay under platform ownership.

{
  "$schema": "https://putnami.dev/schemas/putnami-infra.json",
  "protocolVersion": 2,
  "storage": [
    { "name": "uploads", "access": "readwrite" }
  ]
}

Validate before publishing

Run the broad project contract first, then the Config-specific check when the project publishes native Config:

putnami validate --projects <project>
putnami cloud config validate <project> --env prod
putnami cloud env doctor prod

cloud config validate is local and read-only. It reads the existing schema, authored fields, values, workspace link, version, and repository revision; it does not build, create a package, or contact Cloud. Generate required build artifacts before calling it so you do not validate a stale schema.

cloud env doctor checks every prerequisite the environment needs to deploy and prints the fix for each one that is not met. It only reads.

Do not edit generated contracts

Files below .gen/ are build outputs or immutable publication inputs. In particular, do not hand-edit .gen/version.json, .gen/migration-bundle/, .gen/schema/http-routes.json, or .gen/requirements.json. Change their authored source and regenerate them with the project build instead.

Next