Getting Started

Putnami starts with one workspace model, then lets you choose the runtime surface that fits the first thing you want to build.

Use this page to get the CLI and workspace in place. If you already know the language you want, jump straight to the framework start guide:

You want to build... Start here
React SSR, API routes, or a TypeScript library TypeScript getting started
A Go service or Go library Go getting started
An experimental Python service, library, or data workload Python getting started

Run the verified first-use path

From an empty directory, paste this block into your shell:

curl -fsSL https://putnami.dev/install.sh | bash
export PATH="$HOME/.putnami/bin:$PATH"
putnami init --project webapp --extension ts
putnami serve webapp

The second line makes putnami reachable in the shell you are in. It changes nothing when the command is already reachable.

Supported platforms are macOS and Linux, on amd64 or arm64, and Windows on amd64, which has its own installer, below. Anything else stops with an error naming what it detected, rather than installing a binary that cannot run.

Prerequisites are Bash, curl, tar, either sha256sum or shasum, network access to putnami.dev and the public artifact registry, and network access to the public package registry (https://npm.putnami.dev) used by bun install. The first run also downloads the toolchains it needs: Bun from github.com, with its release read from api.github.com, for a Go project, Go from go.dev, and, for a workspace that adds @putnami/python, uv from github.com. No directory has to be on PATH beforehand: a script running as the child of a pipe cannot change its parent shell, so the block sets PATH itself.

Bun is not a prerequisite. putnami init uses a Bun the machine already holds when it fits. Otherwise Putnami installs Bun at ~/.putnami/toolchains/bun/bun-<version>/bin/bun, from github.com, and refuses an archive whose SHA-256 is not the expected one. It writes nothing to ~/.bun or to a directory on PATH.

What the installer does, and does not do

  • It verifies what it downloads. The registry states the SHA-256 of the binary it serves; the installer computes that hash and compares. It prints Integrity verified (sha256:…) only after the comparison passes, and it refuses to install anything it cannot check.

  • It never asks for your password. No sudo, ever. It installs into ~/.putnami/bin, and links putnami only into a directory that is already on your PATH and writable by you. If there is no writable target, it says which directory and stops — pass --install-dir <dir> to choose another one.

  • It tells you if you need one more line. When it cannot reach your PATH on its own, it prints the exact command to run in the shell you are in:

    export PATH="$HOME/.putnami/bin:$PATH"

    It appends that line to your shell startup file for future shells, and repeats it as the first command under Next:. It also says which putnami your shell now runs, so you never have to guess.

Install a specific version with curl -fsSL https://putnami.dev/install.sh | bash -s -- --version 1.2.3.

Already installed? Update any time with putnami upgrade --global — the install script is only needed once per machine.

On Windows

On Windows 10 version 1803 or later, or Windows 11, on amd64, open a PowerShell window and type the same path. The installer runs inside that window and adds the install directory to its PATH, so the block needs no extra line:

irm https://putnami.dev/install.ps1 | iex
putnami init --project webapp --extension ts
putnami serve webapp

Microsoft Defender blocks the first line when it is passed to powershell -c on a command line. From cmd.exe or Git Bash, download the installer and run it as a file:

curl.exe -fsSLo install.ps1 https://putnami.dev/install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1

The PowerShell installer verifies the download the same way, never asks for administrator rights, installs into %USERPROFILE%\.putnami\bin, and adds that directory to your user PATH. Terminals that were already open keep their old PATH; the installer prints the line to run in them.

Windows on amd64 is supported for people who install and use Putnami. The release gate runs these PowerShell commands on a Windows host created for each QA run. Windows on arm64 is not supported, and contributors to Putnami itself work on macOS or Linux.

Windows needs a few more things:

  • Git for Windows. Workspace hooks run with sh, which Git for Windows provides.
  • Long paths. Enable LongPathsEnabled in Windows and set git config --global core.longpaths true. putnami doctor checks both and prints the command for each.
  • Docker Desktop, only for putnami compose.

Prefer not to run an install script? Read the CLI reference for the command surface and install notes.

What the gate proves

The release gate replays the exact macOS and Linux commands above with an empty workspace, neutral home/config/cache directories, no credentials, and no preinstalled CLI or extensions. init creates and validates:

  • putnami.workspace.json identifies the workspace root
  • putnami.lock.json pins the TypeScript extension and web template
  • webapp/putnami.json identifies the generated project
  • package.json and bun.lock record its dependency state
  • .npmrc maps @putnami dependencies to the public package registry without credentials
  • one Putnami block in AGENTS.md (which CLAUDE.md imports) gives coding assistants the local conventions

serve must emit machine-readable readiness, the starter must answer a real HTTP request successfully, and shutdown must complete within the gate's bound. Open the local URL printed by putnami serve.

On Linux, the gate also pastes the block above, as printed, into an image that holds Bash, curl, tar and a SHA-256 tool and nothing else. There it requires HTTP 200 from every page of the starter and exit status 0 from putnami lint,test,build webapp. It then requires the same from a Go starter: putnami init --project api --extension go, putnami serve api and putnami lint,test,build api.

This guarantee is deliberately narrow. It does not promise support for every shell or Linux distribution, Windows on arm64, other architectures, offline installation, proxy-specific configuration, production deployment, or stable source details in every future generated app. The Go starter is gated on Linux only, and the experimental Python starter is not gated. The checksum proves the bytes match the public registry's digest; artifact signing is a separate, non-goal mechanism.

Experimental Python requires an explicit workspace opt-in after initialization:

putnami deps add @putnami/python
putnami extensions install

What just happened

You interacted with three core pieces of Putnami:

  • Workspace - the root container that organizes projects, extensions, templates, and shared context. Learn more
  • Project - a runnable unit inside the workspace. Learn more
  • Template - the scaffold that gives a new project its language-specific shape. Reference
  • CLI - the command surface for build, test, lint, serve, publish, dependencies, and templates. Reference

You didn't configure anything yet. Defaults are intentional.

Continue from here

Choose the path closest to your first project: