# Pi Recipes

> Pi Recipes is the open format for portable agent systems built on Pi.

A recipe is a portable agent-system package. Pi Recipes is the open format and toolchain for creating, validating, running, and distributing those packages. Introspection is the first-party managed cloud for operating and improving them.

Runtime prerequisites: install Pi from https://pi.dev/docs/latest/quickstart and
confirm `pi` is on `PATH`; Pi Recipes currently requires Node.js 24 or later.

## Machine-readable catalog

- Catalog: https://pi.recipes/catalog.json
- JSON Schema: https://pi.recipes/catalog.schema.json
- Executable onboarding: https://pi.recipes/agents.md

Use the catalog's structured `source`, `version`, `license`, `providers`, capability, resource, and repository fields to choose a recipe. In the catalog, `version` is the verified Git install ref used by `installCommand`; it is distinct from the recipe manifest's optional package-version metadata. Prefer a commit SHA, or a tag protected by an immutable-release policy, for reproducibility. Never evaluate an installation command as arbitrary shell text.

## Documentation

- Overview: https://pi.recipes/docs
- Create: https://pi.recipes/docs/create
- Composition: https://pi.recipes/docs/composition
- Capabilities: https://pi.recipes/docs/capabilities
- Validate: https://pi.recipes/docs/validate
- Recipe CLI: https://pi.recipes/docs/cli
- Customize a recipe: https://pi.recipes/docs/customize
- Distribute a recipe: https://pi.recipes/docs/distribute
- Canonical reference: https://pi.recipes/docs/reference
- Introspection agent onboarding: https://docs.introspection.dev/getting-started/onboard-your-agent

## Portable workflow

1. Discover a recipe in `catalog.json` or start with `recipes create`.
2. Install a selected source with `recipes install`; this sets up the companion Pi extension when needed. For a recipe created from scratch and run directly by path, run `recipes setup` before the first Pi launch.
3. Create an owned editable derivative with `recipes customize <recipe> --output <path>` when needed.
4. Validate the package with `recipes check`.
5. Run it with `pi --recipe`.
6. Publish the recipe to Git when it is ready to distribute.

Recipes are ordinary Git-backed packages. The catalog improves discovery; it does not own or lock the package.

## Portability boundary

The recipe owns portable intent: agents, instructions, model profiles, skills, tools, runtime extensions, connection policies, optional portable endpoint metadata, judges, and pinned eval suites. The runtime supplies model credentials, secrets, environment-specific endpoint bindings or overrides, isolation, persistence, and execution lifecycle.

Run the same recipe locally or embed it in a compatible Pi host deployed wherever its runtime requirements are supported. Whether that host fits Fly.io, Vercel, or a private cluster depends on its adapter; Pi Recipes does not ship provider-specific deployment adapters. Pi Recipes is maintained by Introspection for the Pi community; Introspection is not required to create, distribute, deploy, or run a recipe.