Browse documentation

App Blueprint file format

Author, validate and store a version-1 App Blueprint.

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.