Render Agent Skill

Render — make this repo deploy correctly, wired as code

Take any repo and make it deploy on Render (render.com) in one pass: pick the right

service type, declare everything in a version-controlled render.yaml Blueprint, bind the

port the way Render expects, and wire DATABASE_URL / secrets across services so they

survive rotation. Steer clear of the four traps that eat first deploys: the

"no open ports detected" 502, the free-tier spin-down, the 30-day free-Postgres expiry,

and the 12-hour cron kill.

pick service type → render.yaml at repo root → bind 0.0.0.0:$PORT → wire env across services → push (auto-deploy)
        │                                                                                            │
   web|worker|cron|pserv|static|keyvalue                                       full key surface → references/blueprint-reference.md

Facts here are dated to 2026-06-02 against render.com/docs. Render ships changes; if a

key or limit looks off, confirm against the live Blueprint spec before betting a deploy on it.

The one decision that decides everything: service type

Pick the type before you write a line of YAML. The type sets the billing model, whether

the process gets a public URL, and whether Render expects it to bind a port. Choosing wrong

means a worker that never starts because Render waited for a port, or a 12-hour job that dies

silently as a cron.

| The process… | Type | runtime required? | Gets a public URL? |

| --- | --- | --- | --- |

| serves HTTP/WebSocket traffic | web | yes | yes |

| runs forever, no inbound URL (queue consumer, Celery) | worker | yes | no |

| runs, does work, exits — on a schedule | cron | yes | no |

| internal-only API, reachable only inside Render's network | pserv | yes | no (internal host only) |

| pre-built static assets (SPA, docs) | web + runtime: static | yes (static) | yes |

| cache / queue / Redis-compatible store | keyvalue | no | no (internal) |

runtime enum (everything except keyvalue): node, python, docker, image,

static, go, ruby, elixir, rust.

Blueprint-first: everything lives in render.yaml

**Rule: declare every service, database, and env var group in render.yaml at the repo

root. Touch the dashboard only for sync: false secrets and one-off debugging.** Why: the

Blueprint is the reproducible, reviewable source of truth — it powers preview environments

and a clean re-deploy, while dashboard-only config is invisible state that drifts and can't

be code-reviewed.

Top-level keys: services, databases, envVarGroups, projects, previews.

Minimal correct render.yaml (annotated)

A multi-service app — a Node web service, a Python worker, a nightly cron, a Postgres db,

and a shared env group. Every load-bearing key is commented.

databases:
  - name: app-db
    plan: starter            # NOT free for anything you care about — free expires in 30 days
    postgresMajorVersion: "17"
    region: frankfurt

envVarGroups:
  - name: app-shared
    envVars:
      - key: LOG_LEVEL
        value: info
      - key: SENTRY_DSN
        sync: false          # prompt once at setup; never stored in git

services:
  - type: web
    name: api
    runtime: node
    region: frankfurt
    plan: starter            # $7/mo — avoids the free-tier 15-min spin-down on an API
    buildCommand: npm ci && npm run build
    startCommand: npm start  # MUST bind 0.0.0.0 and read $PORT — see next section
    healthCheckPath: /healthz # gates zero-downtime rollout; new instance must pass first
    preDeployCommand: npm run migrate  # runs before the new instance serves traffic
    autoDeployTrigger: commit          # commit | checksPass | off
    envVars:
      - fromGroup: app-shared
      - key: DATABASE_URL
        fromDatabase:
          name: app-db
          property: connectionString   # never hardcode the URL
      - key: SESSION_SECRET
        generateValue: true            # Render generates a random secret

  - type: worker
    name: jobs
    runtime: python
    plan: starter
    buildCommand: pip install -r requirements.txt
    startCommand: celery -A app worker -l info  # no port — workers don't bind one
    envVars:
      - fromGroup: app-shared
      - key: DATABASE_URL
        fromDatabase: { name: app-db, property: connectionString }
      - key: API_URL
        fromService:                   # reference another service
          name: api
          type: web
          property: hostport

  - type: cron
    name: nightly-cleanup
    runtime: python
    schedule: "0 3 * * *"              # required for cron; 03:00 UTC daily
    buildCommand: pip install -r requirements.txt
    startCommand: python -m app.cleanup
    envVars:
      - key: DATABASE_URL
        fromDatabase: { name: app-db, property: connectionString }

Port binding — do this first (the #1 first-deploy failure)

**Rule: a web service MUST listen on host 0.0.0.0 and read the PORT env var (Render

sets it, default 10000).** If Render detects no bound port within its window, the deploy

fails with "no open ports detected" and visitors get a 502. This is the single most

common first-deploy break — binding localhost/127.0.0.1 or a hardcoded port does it.

// Bad — binds the wrong host and ignores Render's PORT → "no open ports detected"
app.listen(3000);

// Good — bind 0.0.0.0 and honor $PORT
app.listen(process.env.PORT || 3000, "0.0.0.0");

# Bad — gunicorn on a fixed local port
gunicorn app:app --bind 127.0.0.1:8000

# Good — bind 0.0.0.0 and Render's $PORT
gunicorn app:app --bind 0.0.0.0:$PORT

Only web services need this. A worker/cron that tries to bind a port is fine but

pointless; a web service that doesn't is broken.

Wiring env vars across services

**Rule: never hardcode DATABASE_URL, REDIS_URL, or shared secrets as literal value:

strings. Reference the resource** so the value survives a rotation, recreate, or region

move, and so secrets never land in git.

| Form | Use it for |

| --- | --- |

| fromDatabase: { name, property: connectionString } | the Postgres connection string |

| fromService: { name, type, property } | another service's host/port/URL (property: hostport, host, or port) |

| fromGroup: <group-name> | pull a whole shared env var group |

| generateValue: true | a random secret Render generates and stores (session keys) |

| sync: false | a secret you type once at setup; not stored in the repo |

For a Key Value store, reference its connection string the same way you reference Postgres,

via fromService against the keyvalue service.

Migrations and zero-downtime deploys

• preDeployCommand — runs once, before the new instance starts serving traffic. Put

migrations here, not in startCommand (a startCommand migration runs on every instance

and races under multiple replicas).

• healthCheckPath — Render polls it on the new instance and only shifts traffic once it

passes, giving zero-downtime rollout. Point it at a route that checks real readiness.

• autoDeployTrigger — commit (deploy every push), checksPass (wait for CI status),

or off (manual / deploy-hook only).

Free-tier traps

Render's free tier is generous for hobby work and a landmine for anything you care about.

| Trap | What happens | Fix |

| --- | --- | --- |

| Free web spin-down | after 15 min of no inbound traffic the instance sleeps; next request waits 30–60s to wake | Starter at $7/mo per service |

| 750 free instance-hrs/mo | shared across the workspace; spun-down time doesn't count toward it | budget it, or pay Starter |

| Free Postgres expiry | deleted 30 days after creation (14-day grace to upgrade), all data gone; only one free Postgres per workspace | Starter Postgres ($7/mo) from day one for anything real |

| Free Key Value | no disk persistence — data is lost on restart | paid plan if you need durability |

Cron specifics

• schedule: (standard cron expression) is required for type: cron.
• Render guarantees at most one active run at a time — runs don't overlap.
• A run is killed after 12 hours. Anything that can exceed that must be a worker with

its own scheduler/queue, not a cron. A long cron fails silently mid-job — partial work,

no clean error.

Scaling and disk knobs

This is the concrete Render surface, not capacity strategy (that's scaling).

services:
  - type: web
    name: api
    runtime: node
    scaling:
      minInstances: 1
      maxInstances: 4
      targetCPUPercent: 70
      targetMemoryPercent: 80   # autoscale between min/max on CPU/mem
    disk:
      name: data
      mountPath: /var/data
      sizeGB: 10                # a disk PINS the service to ONE instance — blocks horizontal scale

Use numInstances for a fixed replica count instead of scaling when you don't want

autoscaling. A persistent disk and horizontal scaling are mutually exclusive — pick one.

Regions: oregon, ohio, virginia, frankfurt, singapore. Plans: free, starter,

standard, pro, pro plus, pro max, pro ultra.

Anti-patterns

| Anti-pattern | Why it bites | Do instead |

| --- | --- | --- |

| Hardcoding a port (listen(3000)) | "no open ports detected" → deploy fails / 502 | bind 0.0.0.0 and $PORT |

| Hardcoding DATABASE_URL | breaks on rotation / db recreate | fromDatabase reference |

| A long job as a cron | killed at 12h, silent partial work | worker + its own scheduler/queue |

| Free Postgres for production | deleted 30 days after creation | Starter ($7/mo) from day one |

| Secrets as literal value: in render.yaml | leaked in git history | sync: false or generateValue: true |

| Migrations in startCommand | runs on every instance, races under replicas | preDeployCommand |

| Free web service for a real API | cold-start 502s after idle | Starter, or accept it only for a hobby toy |

| Dashboard-only config | invisible drift, no preview envs, no review | declare in render.yaml |

When to hand off

• Schema design, queries, indexing, tuning → ../postgresdb/SKILL.md. This skill only

*provisions and connects* Render's managed Postgres.

• Writing the Dockerfile Render consumes via runtime: docker → docker.
• Registrar-side DNS records for a custom domain → domains-dns. (The Render domains:

block and verification stay here.)

• Cross-platform release strategy, promotion, rollback flow → ../deployment/SKILL.md and

ship. This skill is Render config and platform mechanics.

• Build steps Render's native build doesn't run (custom CI) → github-actions. Render

auto-deploys on push; only reach for Actions when you genuinely need it.

• Capacity/load strategy beyond the scaling: knobs → scaling.
• A different PaaS → its own sibling: ../fly-io/SKILL.md, railway, vercel,

../netlify/SKILL.md, coolify, digitalocean.

Full key surface

The exhaustive render.yaml key tables per service type, all database keys

(postgresMajorVersion, diskSizeGB, readReplicas, highAvailability, previewPlan),

every env-var reference form, region/plan enums, and four complete copy-paste recipes

(Next.js web+pg; FastAPI web+worker+cron+keyvalue; Docker monorepo with rootDir; static

SPA with routes rewrites) live in references/blueprint-reference.md — pull it open when

you need a key this body didn't cover.