App Blueprints are project-scoped, declarative setup definitions. Version 1 validates, stores, and displays a specification. It does not create an App or preview, deploy anything, allocate storage, or select source code. Updating a blueprint replaces its current specification; blueprints do not retain historical revisions.
Blueprint files are JSON. Objects are exact: unknown fields are rejected, and
optional fields must be omitted rather than set to null.
Minimal public HTTP runner
The CLI includes a complete stateless example that works offline from any directory:
rp app blueprint example > blueprint.json
It declares one public web runner on port 6161 and omits environment and
volume requirements, making it eligible for the current stateless task-preview
slice. Use the example printed by the App CLI reference for the installed version.
The validator fills omitted context, depends, required_env, and volumes
with ., [], [], and [] when it stores or displays the specification.
For dependencies, health checks, required environment names, and a volume, run
rp app blueprint example --full. This is a general App Blueprint; its
required_env and volumes make it ineligible for the current task-preview
slice.
Top-level fields
| Field | Required | Meaning |
|---|---|---|
version |
yes | Integer 1. Other versions are rejected. |
units |
yes | Non-empty array of unit objects. Unit names must be unique. |
public_unit |
no | Name of the one publicly routed unit. It must identify a runner with http_port. Omit it for a worker-only blueprint. |
Unit fields
| Field | Required | Meaning |
|---|---|---|
name |
yes | Unique 2–32 character name: lowercase letters, numbers, or hyphens, starting with a letter and ending with a letter or number. |
type |
yes | runner or builder. |
containerfile |
yes | Relative file path within the source checkout. Absolute paths, . and parent, current, or empty path segments are rejected. |
context |
no | Relative source-checkout directory used as build context; defaults to .. Other current segments, absolute paths, and parent or empty segments are rejected. |
http_port |
no | Integer from 1 through 65535. Allowed only on runners. The unit is eligible for public routing only when selected by public_unit. |
depends |
no | Array of unique unit names; defaults to []. Every name must exist, self-dependencies and cycles are rejected. |
health |
no | TCP or HTTP health-check object. Builders cannot declare health checks. |
required_env |
no | Array of unique environment variable names matching [A-Z_][A-Z0-9_]*; defaults to []. Values are not part of a blueprint. |
volumes |
no | Array of named container mounts; defaults to []. Names and mount paths must each be unique within the unit. |
An HTTP health check has the form {"type":"http","path":"/health"} and
requires the same unit to declare http_port. Its path must be absolute and
cannot contain empty or parent segments. A TCP check has the form
{"type":"tcp","port":9000}; its port must be an integer from 1 through
65535.
A volume has the form
{"name":"storage","mount_path":"/app/storage"}. Its name follows the
same 2–32 character syntax as unit names. The mount path is an absolute
container path other than /, without empty or parent segments. Blueprints do
not contain host paths and do not allocate the named volume.
Source and runtime boundary
Paths are interpreted relative to source selected later by an App or preview; the blueprint itself cannot contain a branch, tag, commit SHA, repository, or host. It also cannot contain environment values, credentials, commands, hostnames, runtime status, or live volume identifiers. The validator rejects these as unknown fields. Storing a blueprint has no runtime side effects.
Authoring workflow
Validate before storing a file:
rp app blueprint example > blueprint.json
rp app blueprint validate --file blueprint.json
rp app blueprint create website --file blueprint.json --default
rp app blueprint example --full > blueprint.json
rp app blueprint update website --file blueprint.json
rp app blueprint show website --file blueprint.json
validate, create, and update also accept --file - to read JSON from
standard input. show writes formatted JSON to standard output unless
--file supplies an export path, making export/edit/validate/update a complete
file-based workflow.
At most one blueprint can be the project default. --default marks the created
or updated blueprint as default, but refuses to silently replace a different
default. --no-default is valid only when updating the current default and
requires confirmation in the browser before either the specification or the
default status changes.
Validation failures
Malformed JSON is rejected locally as invalid blueprint JSON. Schema errors
identify the offending field or unit, including unknown fields, missing or
unsupported versions, empty units, invalid names or paths, invalid ports,
duplicate names, missing dependencies, dependency cycles, invalid public-unit
selection, and health checks not allowed by the unit type. validate performs
no storage or runtime operation.