Packaging a recipe

The registered recipe path is the recipe directory recorded for a runtime when it was created — the path a runtime’s recipe registration points at (see CLI → runtimes). A managed task uses that path at the Git commit selected for its environment. Source outside it is not part of the deployed recipe, and moving the environment to another version affects new tasks rather than a task that is already running.

What is included

Introspection prepares the files under the registered recipe path after applying the root .recipeignore. Before the agent starts, it installs production Node dependencies, prepares declared Python requirements, and validates requested system capabilities. Missing source, invalid declarations, or unsatisfied requirements prevent the task from starting.

Keep every file needed to construct or run the recipe inside the registered path. This includes agent definitions, extensions, skills, runtime projects, and lockfiles.

Exclude authoring-only files

A root .recipeignore controls which paths are absent from the deployed recipe. It uses Gitignore-style glob patterns, including ! negation.

README.md
.pi/
evals/
python/tests/
schemas/
**/__pycache__/
**/*.pyc
**/*.egg-info/

Do not ignore anything needed to construct or execute the recipe, including declared agents, extensions, skills, runtime projects, lockfiles, or files under files/. The ignore file is a packaging boundary, not a security boundary: it does not stop Git from tracking a file or remove a structural source from validation. Recipe extensions remain trusted executable application code. Keep credential-bearing local configuration outside the portable package and ignored by Git itself.

Cloud validation guardrails

Cloud validation first enumerates the registered recipe path, then reads the structural sources needed to check it: YAML definitions, SKILL.md files, package and lock manifests, and the local MCP example when present. The platform bounds tree enumeration, the number and combined size of those selected sources, and validation time so an unusually large repository cannot consume an unbounded validation worker.

These checks are not a maximum size for the complete packaged recipe. Binary inputs and ordinary implementation files that the structural validator does not read are not counted as validation-source bytes, though runtime packaging and task-file limits still apply separately. If cloud validation reports that it could not finish rather than returning file diagnostics, run introspection check locally, then narrow the registered recipe path or split oversized structural definitions before requesting a fresh validation. A recipe with diagnostics is invalid; a failed validation is an incomplete validation attempt.

Supply files to every task

Put static inputs that every task should receive in the conventional files/ directory. Introspection preserves nested paths and binary contents and makes the files available alongside restored task files and uploads. Recipe-provided files are read-only.

spreadsheet-agent/
├── files/
│   ├── clean-statement.xlsx
│   └── statement-with-errors.xlsx
├── python/
├── agents/
└── package.json

These packaging limits apply to the recipe’s own files/ directory: each recipe-provided file may be at most 10 MiB, and the directory may contain at most 25 MiB in total. Files the task reads or writes in its workspace at run time are governed by the separate per-file limit in State and artifacts. Symlinks are rejected. A path collision with a restored task file or upload also prevents startup; Introspection never silently chooses one source or overwrites another.

Use files/ for fixtures, templates, reference documents, and other inputs. Keep executable application code in the recipe itself, and write outputs to the task’s files area rather than back into files/.

Task artifacts

Unchanged recipe inputs are not uploaded again as generated artifacts. Files the agent creates or changes in the task’s files area are versioned through the Files API at checkpoints and task completion. See State & artifacts for the durable file model.

See Operating runtimes for how the pinned recipe fits into managed task startup.