Blueprint YAML reference
Supported manifest fields, service types, configuration mappings, and validation rules.
Openstead manifests use UTF-8 YAML with a top-level services list. They support 1–30 service definitions and a maximum size of 64 KiB. YAML anchors and aliases are rejected; repeat each service's settings explicitly.
Minimal manifest
services:
- name: example-api
type: web
plan: free
runtime: node
startCommand: npm startEvery service needs a unique name: up to 63 lowercase letters, digits, and hyphens, starting with a letter or digit. Always declare type and plan explicitly so a manifest communicates its intended resources.
Service types
type | Service |
|---|---|
web | Public web application or API. |
static | Built static site. |
private | Internal network service. |
worker | Long-running background process. |
cron | Scheduled command. |
postgres | Managed PostgreSQL. |
mysql | Managed MySQL. |
redis | Redis-compatible Key Value. |
The parser accepts pserv, background_worker, and keyvalue as aliases for private, worker, and redis. Prefer the canonical names above.
Top-level service fields
| YAML field | Equivalent service configuration | Meaning |
|---|---|---|
repo | repository | HTTPS repository URL; otherwise inherited for repository services. |
branch | branch | Source branch. |
runtime | runtime | auto or a supported runtime. |
rootDir | rootDirectory | Build root relative to the repository. |
buildCommand | buildCommand | Build command override. |
startCommand | startCommand | Command for the running service. |
preDeployCommand | preDeployCommand | Command before release; paid instance required. |
staticPublishPath | publishDirectory | Static build output directory. |
schedule | schedule | Cron expression for a cron service. |
plan | plan | Valid instance plan for the service kind. |
configuration | Configuration mapping | Additional supported service configuration. |
When the same setting appears both at the service top level and inside configuration, the top-level field wins. Avoid specifying a setting twice.
Configuration mapping
configuration accepts the service configuration fields defined in the public API specification. Common fields include:
| Field | Values and constraints |
|---|---|
sourceType | repository, image, or none. |
buildMethod | railpack, dockerfile, or image. |
image, registryId | Container reference and optional workspace registry UUID. |
dockerfilePath, dockerContext | Repository-relative Docker paths. |
autoDeploy | off, commit, or checks. |
port | Integer from 1 to 65535. |
healthCheckPath | Empty or a path starting with /. |
region | A region ID from the catalog. |
replicas | 1–20, subject to service and plan constraints. |
timezone | IANA timezone, such as Africa/Lagos. |
timeoutSeconds | Command timeout; cron maximum is 43200. |
databaseName, databaseUser | Supported database/user identifiers. |
databaseVersion | PostgreSQL 16, 17, or 18; MySQL 8.4. |
backupEnabled, backupRetentionDays | Backup settings for supported databases. |
Paths cannot contain parent traversal or backslashes. Unknown configuration keys are rejected. Omitted settings use defaults on a new service and retain existing values during synchronization.
runtime: auto allows build detection. Other runtime values are docker, node, python, go, php, java, ruby, rust, elixir, deno, dotnet, gleam, cpp, static, and shell. Use Docker when your application needs dependencies or startup behavior outside an automatic build.
Plans
Application plans are free, starter, builder, growth, and scale. Free application instances are limited to web services and static sites, with a single replica and no paid-only settings.
PostgreSQL uses postgres-starter or postgres-standard. MySQL uses mysql-free, mysql-starter, or mysql-standard. MySQL Free is limited to one database per workspace. Read the catalog and current pricing before deploying a manifest containing paid resources.
Managed MySQL uses one private instance on port 3306 with sourceType: none. Repository build commands, HTTP domains, and auto-deploy settings do not apply to it. MySQL Free backup retention is 1–7 days; other database plans accept 1–30 days.
Secrets and other resources
Inline envVars values are rejected. An envVars entry without a value does not create or wire a variable. Use service variables or environment groups after configuration is created.
Render-specific directives such as fromDatabase, generateValue, sync, and top-level databases are not Openstead manifest features. Define databases inside services; configure variables, persistent disks, custom domains, and other service resources through their dashboard controls.
Validate
Use the dashboard's validation control or the CLI:
openstead blueprints validate --file openstead.yamlValidation checks the manifest without provisioning resources. Applying or deploying still checks workspace quotas, source access, current entitlements, and service payment requirements.