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 prodcloud 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.