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

Install putnami

curl -fsSL https://putnami.dev/install.sh | bash

Supported platforms are macOS and Linux, on amd64 or arm64. On Windows, install inside WSL2. Anything else stops with an error naming what it detected, rather than installing a binary that cannot run.

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"

    and appends it to your shell startup file for future shells. The last line it prints is 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.

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

Create a workspace

mkdir my-project && cd my-project
putnami init

This creates the workspace root and shared assistant context:

  • putnami.workspace.json identifies the workspace root
  • .AI/context.md, CLAUDE.md, and AGENTS.md give coding assistants the local conventions
  • installed extensions and templates become available to every project

Each project inside the workspace is identified by its own putnami.json.

Create your first project

Pick the template that matches the surface you want:

putnami projects create web --template typescript-web
putnami projects create api --template go-server

# Experimental Python requires an explicit workspace opt-in.
putnami deps add @putnami/python
putnami extensions install
putnami projects create jobs --template python-server

Then install/sync dependencies and run the selected project:

putnami deps install
putnami serve web

Open the local URL printed by putnami serve.

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: