Overview

The platform is the layer that turns a Putnami workspace into a running system. Your workspace is the architecture: every project that declares how it runs is a deployable unit, and the platform runs all of them from one control plane.

A framework that ignores deployment is incomplete. The gap between "runs on my machine" and "runs in production" is where environments diverge, secrets go missing, and logs disappear. The platform closes that gap by making the runtime a property of the same versioned workspace you build in — not a separate system you wire up by hand.

How it reaches you

The platform is one CLI extension, @putnami/cloud. Installing it adds cloud commands to putnami and connects your workspace to a Putnami Cloud control plane. You keep using the CLI you already have.

   your workspace                     Putnami Cloud
  ┌───────────────┐   putnami cloud  ┌────────────────────────┐
  │ projects      │ ───────────────▶ │ control plane          │
  │ infra/        │     deploy       │  · builds & releases   │
  │ conf/         │ ◀─────────────── │  · runtime (hosting)   │
  │ @putnami/cloud│    config/creds  │  · registries, data,   │
  └───────────────┘                  │    storage, telemetry  │
                                     └────────────────────────┘

What "deployable" means

A project is deployable when it carries an infra/runtime.json describing how it runs (ingress, scaling, resources). The putnami deploy verb activates on that file. Projects without it — libraries, tools — are built and published but not run as services.

Project has… The platform…
infra/runtime.json runs it as a service (putnami deploy)
a config schema + conf/env.<env>.yaml resolves and serves its config
a migration bundle applies migrations before the new revision serves
publishable archives / packages publishes them to the registries

The lifecycle in one place

  1. Install the extension — Install the cloud extension.
  2. Log in — OAuth device authorization, plus per-registry credentials — Log in.
  3. Set up — link the repository to a Cloud workspace — Set up the workspace.
  4. Deploy — publish artifacts, then release a new revision — Your first deploy.

Everything after that — environments, the build cache, registries, the managed runtime, data, storage, observability, and events — is covered from the platform index.

Design guarantees

These hold across local, preview, and production; they are constraints, not features to add later.

  • Deterministic and reviewable. Git defines intent. A deployment is a pure function of versioned state, and each running revision is attributable to a commit.
  • Observable by construction. The runtime emits structured signals by default; the same shape appears everywhere.
  • Secure by default, fails closed. Boundaries are declared at interfaces; unsafe paths require explicit acknowledgment.
  • Your data stays yours. Databases and buckets live in stores you control; the platform layer does not own application data.

Next