Deploy & hosting

A project deploys through an environment that follows a channel. A merge to main publishes the project's artifacts into an immutable release set and moves a channel. Every environment that follows that channel then deploys the projects whose content changed. A project becomes deployable when it has an infra/runtime.json; that file declares how the service is hosted — ingress, scaling, resources.

Each release is attributable to a specific commit. Zero-downtime cutover is the default, and the previous revision keeps serving until the new one is Ready.

Deploy

There is no deploy command. You set an environment up once, then merge:

Want to… Do this
Check what an environment still needs putnami cloud env doctor <env>
Apply the fixes your workspace owns putnami cloud env enable <env>
Deploy Merge to main; the environment follows its channel
See what runs where putnami cloud env status <env>
Read one release putnami cloud deploy status <release-id>
Promote or roll back an environment `putnami cloud channels set --from <channel

Start with the walkthrough: Your first deploy. Environments follow channels covers every field and outcome.

Where your image goes

A deploy publishes your container image to the platform OCI registry, then asks the control plane to run that exact digest. You declare one coordinate:

{
  "options": {
    "publish": { "dockerRegistry": "oci.putnami.dev/<namespace>" }
  }
}

Declare the bare host or a namespace under it; both work. With nothing declared, the deploy uses oci.putnami.dev.

The control plane copies the published digest into the registry your runtime pulls from and pins the new revision to the copy. You do not name that registry, grant it access, or know which cloud it belongs to — the request carries only the registry you published to and the digest you published. That is the same request whichever channel move or release triggered the deploy, so every path rolls the identical image.

Declaring a cloud provider registry path instead (for example <region>-docker.pkg.dev/<project>/<repo>) skips the copy: the revision pulls straight from where you published. Use it only when you own that registry.

Hosting: infra/runtime.json

A deployable project declares its runtime in infra/runtime.json. The fields below are verified against services running in production today; the managed runtime page covers scaling, config, and bindings in depth.

{
  "ingress": { "domains": ["service.example.com"] },
  "scaling": { "max": 2, "concurrency": 500 },
  "resources": { "cpu": "1000m", "memory": "512Mi" }
}
Field Meaning
ingress.domains custom hostnames the service answers on
ingress.public set false for an internal-only service (no public URL)
scaling.max maximum active instances; the CPA always owns a zero floor
scaling.concurrency requests per instance before scaling out
resources.cpu / memory per-instance resources
security.platformAuth "disabled" when the service handles its own authentication

Infra protocol v2 does not expose scaling.min. All managed services scale to zero and use request-based CPU; those settings are CPA-owned platform invariants rather than manifest options. A workload that must continue after an HTTP response must use a job or worker execution contract instead of changing the service billing posture.

Ship the declaration with each release

When an environment follows a channel, each release set can carry the workload's deployment declaration: its infra/runtime.json settings and its resolved requirements (databases, events, storage, secrets, scheduled jobs) as one document. The platform then sets up the service, its scheduled jobs and its domains from the release set it deploys. A change to infra/runtime.json or to a schedule ships with the next channel move, like a code change.

Turn it on per workload, in the workload's own putnami.json:

{
  "options": {
    "@putnami/go": { "deployment": true }
  }
}

Use @putnami/typescript instead for a TypeScript workload. The workload must also be continuously deployed (options["@putnami/cloud"].deploy.enabled: true) and publish a Config member (a @putnami/cloud:publish-config namespace). Your Go or TypeScript extension must be a version that has the deployment package step. The setting counts only in the workload's own putnami.json, not in putnami.workspace.json.

When What happens
The first release after you turn it on The workload rolls once, even when its code did not change.
Only the declaration changes in a release The workload rolls once.
A channel moves back to a set from before you turned it on The workload rolls once and uses the declaration its last release without a member recorded.
You turn it off The next release carries no declaration. The workload rolls once and uses the declaration its last release without a member recorded.
The workload publishes an image channel No declaration is published.

To undo a bad declaration, turn the setting off or fix the declaration and release again. Do not downgrade the framework below the version that added the deployment package step once a release set carries a declaration: older versions refuse those release sets.

Public vs authenticated

Ingress controls reachability. Set ingress.public: false for a service with no public URL. A public service that owns its own authentication declares security.platformAuth: "disabled"; use the current runtime schema when the platform, rather than the service, is to enforce authentication.

Generated HTTP route intent

Frameworks may emit a canonical route inventory at .gen/schema/http-routes.json. Deploy carries that artifact byte-for-byte, validates the putnami.http-routes.v1 protocol and digest before provisioning, and records the exact inventory on the deployment. A route-only change or removal is release content, so it prevents an otherwise-unchanged deploy from being skipped.

Path enforcement is default-off. A project opts its release into the generated route policy through putnami.json:

{
  "options": {
    "@putnami/cloud": {
      "deploy": { "enforceHttpRoutes": true }
    }
  }
}

The managed Putnami gateway currently suspends this opt-in at the operator master switch: generated artifacts are still carried and validated, but the effective gateway policy remains host-to-service routing without a path/method allowlist. Do not rely on enforceHttpRoutes for 404 filtering until a scalable replacement is announced.

An opted-in deploy fails before provisioning when the generated artifact is missing, malformed, noncanonical, or uses an unsupported protocol version. Without the setting, a project that emits no artifact keeps the existing hostname-level routing behavior. When the managed gateway, its shared reject backend, and the operator master switch are configured, enforcement projects only publicEdge: true exact, slash-terminated prefix, and supported segment-template paths to the workload; all unmatched paths go to the reject backend without invoking the workload's Cloud Run service. Removing a declared path removes its gateway rule. Disable the setting and merge to roll the host matcher back to legacy host-default routing. Each public route method is enforced with an exact gateway :method match; undeclared methods and private methods on the same path go to the reject backend without reaching the workload.

Pages

Page Status
Your first deploy Ready
Environments follow channels Ready
Environments (prod, preview, per-env config) Planned
Preview environments (per-branch URLs) Planned
Rollback Planned
Ingress & custom domains Planned
Public vs authenticated services Planned

Next