render.yaml for coding agents: let your agent write and validate Blueprints

Your coding agent can already create Render resources for you. The harder part is seeing exactly what it plans to create before anything happens. A render.yaml Blueprint gives you that checkpoint. The agent writes infrastructure as a file, and you review the file like any other code change. For a broader look at the tools agents can use with Render, see how to build, deploy, and operate with coding agents on Render.

Blueprints work well as the interface between an agent and Render for three reasons:

• The diff is reviewable. Every service, database, and environment variable appears in a pull request (PR) before it reaches production.
• The setup is reproducible. The same file recreates the same stack, so you don't depend on a sequence of one-off agent actions.
• A Blueprint covers options the MCP server can't set at creation time. The Render MCP server can create web services, static sites, cron jobs, Render Postgres databases, and Render Key Value instances, and it doesn't yet support other service types. It also doesn't support every configuration option when creating services. For example, you can't use it to create image-backed services or to set up IP allowlists. A Blueprint can declare a Workflows service, an image-backed service with runtime: image and image.url, and a Key Value ipAllowList.

In this tutorial, your agent writes one render.yaml with five resource types and validates it. You then apply it with preview environments. The one caveat is that workflows don't appear in preview environments.

The workflow at a glance

Here's the loop you'll set up. The rest of the article covers each step in detail.

Steps 2 through 4 happen before you see anything. The goal is for every PR you review to contain a Blueprint that has already passed validation.

Have the agent write the Blueprint with the render-blueprints skill

The render-blueprints skill authors and validates render.yaml Blueprints. It covers wiring services together with fromDatabase, fromService, and fromGroup, configuring preview environments, validating against the schema, and fixing immutable field errors. Per the CLI reference, render skills install installs skills to detected AI coding tools (Claude Code, Codex, OpenCode, Cursor) and prompts you to select which skills to install.

The skill shapes how your agent works in a few ways:

• It loads the current spec first. Before the agent creates or modifies a Blueprint, the skill directs it to read a reference covering the current specification fetch, validation, repository sync, and safety workflow.
• It checks service types and plans. The skill points the agent to dedicated references for choosing service types and for current compute plan IDs, so the agent doesn't copy plan names from old examples.
• It asks about previews. When a preview request is underspecified, the skill has the agent establish the generation mode, retention period, preview compute plans, and any resources you expect to exclude.
• It recommends a structure. For multi-service apps, the skill recommends the projects/environments pattern over flat top-level services and databases lists.

When your prompt names every resource and every relationship, the agent has less to guess. For example, you might write:

The last paragraph matters most. Without it, an agent may stop after drafting and leave validation to you.

Worked example: one render.yaml, five resource types

The following simplified example shows the shape of the file your agent should produce. It illustrates the pattern, so adapt names, runtimes, commands, regions, and plans to your app before you apply it.

Before you apply a file like this, make sure your repository has the application code it points to:

• A package.json whose build produces dist/workflow.js (your task definitions) and dist/trigger-tasks.js (the cron script).
• Workflow tasks defined with the Render SDK, which is available for TypeScript and Python.
• A Render API key you can enter for RENDER_API_KEY, because the file declares that key without a value.

If you're new to the Workflows model, Durability as code: Introducing Render Workflows explains the background.

How the pieces connect

Connection strings come from references. Instead of a hardcoded URL, the web service uses fromDatabase to pull connectionString from db and fromService to pull connectionString from cache. Database references can also expose connectionPoolString, user, password, and database. These references resolve by name, which is why the comments flag the matching names.

The cron job triggers tasks through code. A cron job runs and then exits on a defined schedule. It doesn't expose a URL, but it can send outbound requests to other service types. You can trigger workflow task runs through the Render SDK, API, CLI, or Dashboard. In this example, the Blueprint owns the schedule and dist/trigger-tasks.js decides which tasks run. Triggering task runs from code requires a Render API key. Each task is identified by its slug, which has the format {workflow-slug}/{task-name}, so every slug below starts with jobs-workflow/. A minimal sketch of that script looks like this:

The second argument passes the task's input arguments, and a task that takes zero arguments gets an empty list, []. See Triggering Task Runs for more options, such as passing arguments as an object or waiting for a run to finish. If you're weighing a cron job against a long-running worker, the service types overview compares them.

Secrets stay out of the file. Service environment variables can pull values from other resources instead of hardcoding secrets. For values that no other resource provides, such as the API key in this example, sync: false declares the key without putting a value in the file. For random secrets your app generates for itself, generateValue sets a randomized, base64-encoded, 256-bit value.

Previews sit at the top level. The previews block applies to the whole Blueprint, not to a single service. The section on applying the Blueprint covers how it behaves.

Validate from the CLI

The render-blueprints skill validates YAML against Render's schema or with the CLI. You can check your current version with render --version. For background on the CLI itself, see Introducing Render's New CLI and Refreshed Dashboard. The CLI reference documents the Blueprint validation command. Here's a session where your agent checks the CLI version and then validates the file:

The CLI reference also documents the skills subcommands, including update, remove, and list. Run update when you want the agent working from the latest skill guidance.

Validation catches problems a quick read of the YAML can miss. It checks YAML syntax, the schema (required fields and types), semantics such as valid plans and regions, and conflicts with existing resources. Some fields can't change after a resource exists. These include a service's type and region, and a database's name, databaseName, user, region, and postgresMajorVersion. Render may reject edits to these fields, or the edits may require replacement resources. The skill helps the agent fix immutable field errors.

The loop you want looks like this:

1. The agent runs render blueprints validate render.yaml.
2. The agent reads each error and edits the field it names. For example, it moves a misplaced database from services to databases, or adds a missing schedule to the cron job.
3. The agent runs the same command again.
4. The agent opens the PR only after a clean pass, and says so in the PR description.

You can also run the same command as a check in your CI pipeline once the CLI is authenticated with an API key in non-interactive mode. That way, a Blueprint edit that skips the loop still gets validated. Because this loop runs before review, the PR is less likely to contain syntax problems, so you can focus on intent. You spend your review time on questions like "should this database exist?" instead of "is this indented correctly?"

Apply it and turn on Blueprint-driven preview environments

After you approve and merge the PR, create the Blueprint from your repository in the Render Dashboard, or let an existing Blueprint sync the change. The Blueprint setup docs cover both paths. Keep each resource under one Blueprint. Render's guidance is to manage each resource with at most one Blueprint.

The top-level previews block in the same render.yaml controls Blueprint preview environments. The previews.generation field accepts off (the default), manual, or automatic, and previews.expireAfterDays deletes a preview environment after that many days without new commits, with each push resetting the timer. With generation: automatic, Render creates the Blueprint's preview environment for pull requests, including the resources that Blueprint declares. To size preview instances, use previews.plan and previews.numInstances on compute services, and previewPlan on Key Value and Postgres.

Two details trip up agents:

• A service-level previews.generation controls that service's independent service previews. It doesn't exclude the service from the Blueprint preview environment.
• sync: false variables aren't copied to preview environments. The documented workaround is to create an environment group in the Dashboard, add the secret to it, and reference that group from your Blueprint.

For details on per-PR behavior, see Render's preview environments docs.

Common agent mistakes in render.yaml

Tell your agent to validate after every edit, not just once.

Where to go next

Your agent writes the Blueprint with the render-blueprints skill and validates it from the CLI until it passes. You review the diff, apply it, and let preview environments run for each PR, knowing that Render skips the workflow there.

For deeper treatment of each piece:

• Blueprint YAML reference for every field, including workflow-specific support
• CLI reference for validation and skills commands
• LLM support for installing Render skills and plugins for your coding agent.
• Render Workflows for defining and triggering tasks
• Preview environments for per-PR behavior and sizing

Frequently asked questions