Render

View saved version →

---
name: render-background-workers
description: >-
  Sets up and configures background workers on Render for queue-based job
  processing. Use when the user needs to process async jobs, consume from a
  queue, run Celery/Sidekiq/BullMQ/Asynq/Oban workers, handle graceful
  shutdown with SIGTERM, wire a worker to Key Value (Redis), or choose between
  workers and cron jobs for background work.
  Trigger terms: background worker, async jobs, queue consumer, Celery,
  Sidekiq, BullMQ, Asynq, Oban, job processing, SIGTERM, graceful shutdown.
license: MIT
compatibility: Render background worker services
metadata:
  author: Render
  version: "1.0.0"
  category: compute
---

# Render Background Workers

This skill explains **worker** services on Render: processes that **consume jobs from a queue** instead of serving HTTP. Pair with **render-blueprints**, **render-env-vars**, and **render-networking** when wiring `render.yaml` and private connectivity.

## When to Use

- Designing or debugging **queue-backed workers** (Celery, Sidekiq, BullMQ, Asynq, etc.)
- Choosing between a **worker**, **Cron Job**, or **Workflow** for background work
- Configuring **Render Key Value** as a **broker** (not a cache) with correct **eviction policy**
- Implementing **graceful shutdown** so in-flight jobs are not lost on deploy

Per-framework setup and signal-handling detail: `references/queue-framework-setup.md`, `references/graceful-shutdown.md`.

## How Workers Work

- **Long-running services** with **no inbound (HTTP) traffic**. Render does not expose a public URL or internal hostname for workers the way it does for web or private services—**workers cannot receive private network traffic directed at them**.
- The typical pattern is a **poll loop**: the process connects to a **queue backend** (often **Render Key Value**, Redis-compatible **Valkey 8**) and **pulls jobs**.
- Workers **can initiate outbound connections** on the private network—to **PostgreSQL**, **Key Value**, **private services**, **web services** (internal URLs), and the public internet—subject to your plan and firewall rules.

## Queue Framework Overview

| Framework | Language | Queue backend | Notes |
|-----------|----------|---------------|--------|
| Celery | Python | Redis / Key Value | Most common Python task queue |
| Sidekiq | Ruby | Redis / Key Value | Standard for Rails |
| BullMQ | Node.js | Redis / Key Value | Modern Node queue (Redis-based) |
| Asynq | Go | Redis / Key Value | Go async task processing |
| Oban | Elixir | **Postgres** (not Redis) | Queue stored in the database |

## Pairing with Key Value

- Use **Render Key Value** as the **job broker** when your framework expects Redis.
- Set **maxmemory policy** to **`noeviction`**. **`allkeys-lru`** and similar policies are for **caches**; evicting queue keys **drops jobs**.
- Wire **`REDIS_URL`** (or your framework’s equivalent) via **`fromService`** with `type: keyvalue` and `property: connectionString` in the Blueprint.
- **Blueprints require `ipAllowList`** on Key Value—include the CIDRs that should reach the instance (often `[]` for private-network-only access; see **render-blueprints** / Key Value field reference).

See `references/queue-framework-setup.md` for minimal app + YAML examples.

## Worker vs Cron vs Workflow

| Need | Use | Why |
|------|-----|-----|
| Always-on queue consumer | **Background Worker** | Polls continuously; long-lived process |
| Periodic scheduled task | **Cron Job** | Runs on a schedule, **exits**; **12h max** per run |
| Distributed parallel compute | **Workflow** | Each run gets its own instance; fan-out patterns |
| High-volume or bursty jobs | **Workflow** | Scales per run; **no idle instance cost** between runs |

## Graceful Shutdown

- Before stopping an instance, Render sends **`SIGTERM`**, then waits up to **`maxShutdownDelaySeconds`** (**1–300**, **default 30**) before **`SIGKILL`**.
- Workers should: **(1)** stop accepting new jobs, **(2)** finish the current job or **checkpoint** progress, **(3)** close connections, **(4)** exit **0**.
- Set **`maxShutdownDelaySeconds`** to at least your **longest safe job duration** (see Dashboard or Blueprint).

Language- and framework-specific handlers: `references/graceful-shutdown.md`.

## Blueprint Configuration

Minimal pattern: **`type: worker`**, **`runtime`**, **`buildCommand`**, **`startCommand`**, and **`envVars`** wired from Key Value.

```yaml
services:
  - type: keyvalue
    name: jobs
    plan: starter
    region: oregon
    ipAllowList: []

  - type: worker
    name: task-worker
    runtime: python
    region: oregon
    plan: starter
    buildCommand: pip install -r requirements.txt
    startCommand: celery -A tasks worker --loglevel=info
    envVars:
      - key: REDIS_URL
        fromService:
          name: jobs
          type: keyvalue
          property: connectionString
```

Optional: **`maxShutdownDelaySeconds`** on the worker service for longer draining jobs.

## References

| Topic | File |
|--------|------|
| Celery, Sidekiq, BullMQ, Asynq, Oban setup + YAML | `references/queue-framework-setup.md` |
| SIGTERM, `maxShutdownDelaySeconds`, per-language patterns | `references/graceful-shutdown.md` |

## Related Skills

- **render-deploy** — First deploy, CLI, service creation
- **render-blueprints** — Full `render.yaml` schema, `fromService`, projects
- **render-networking** — Private URLs, what can call what
- **render-scaling** — Worker plans, instance counts, limits

Referenced files: 2

View saved version →

---
name: render-blueprints
description: >-
  Authors and validates render.yaml Blueprints for Render infrastructure. Use
  when the user needs to write or edit a render.yaml, wire services together
  with fromDatabase/fromService/fromGroup, set up projects and environments
  for multi-service apps, configure preview environments, validate against
  the schema, or fix immutable field errors. Trigger terms: render.yaml,
  Blueprint, IaC, fromDatabase, fromService, envVarGroups, previews, projects,
  environments.
license: MIT
compatibility: >-
  Git repository on GitHub, GitLab, or Bitbucket for Blueprint sync. Render CLI
  v2.7.0+ recommended for `render blueprints validate`. IDEs can validate
  against the public JSON Schema URL below.
metadata:
  author: Render
  version: "1.0.0"
  category: configuration
---

# Render Blueprints (render.yaml)

Blueprints define Render infrastructure as YAML (commonly `render.yaml` at the repo root). This skill focuses on **authoring**, **wiring**, **projects/environments**, **previews**, **validation**, and **immutable fields**. Heavy detail lives under `references/`.

## When to Use

Apply this skill when the user:

- Creates or edits a `render.yaml` / Blueprint
- Wires databases, private services, or Key Value into app env vars
- Groups services with **projects** and **environments**
- Configures **preview environments** for pull requests
- Validates YAML against Render’s schema or CLI
- Asks what can or cannot change after a resource is created

For end-to-end deploy flows and MCP/CLI operations, see **render-deploy**. For env var strategy outside Blueprint syntax, see **render-env-vars**. For Docker-specific Blueprint fields, see **render-docker**.

## Blueprint Structure

### Top-level keys

| Key | Purpose |
|-----|---------|
| `services` | Web, worker, cron, private service, Key Value, static (via `web` + `runtime: static`) |
| `databases` | Managed PostgreSQL instances |
| `envVarGroups` | Reusable env var sets attached to services |
| `projects` | Optional grouping; contains `environments` and service lists |
| `previews` | Defaults for PR preview environments |

A Blueprint may also use patterns like **ungrouped** resources vs **environment-scoped** lists, depending on whether you adopt the projects model. Avoid duplicating the same logical resource in multiple places (see `references/common-mistakes.md`).

### Schema and IDE validation

- **JSON Schema URL:** `https://render.com/schema/render.yaml.json`
- Configure your editor to associate `render.yaml` with that schema for completions and diagnostics.

### Minimal example: web + PostgreSQL

```yaml
databases:
  - name: mydb
    plan: basic-256mb
    region: oregon

services:
  - type: web
    name: api
    runtime: node
    region: oregon
    plan: starter
    buildCommand: npm ci && npm run build
    startCommand: npm start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: mydb
          property: connectionString
```

## Service Types

| `type` | Role |
|--------|------|
| `web` | Public HTTP service (use `runtime: static` for static sites) |
| `pserv` | Private service (internal HTTP/TCP; not public) |
| `worker` | Long-running background process |
| `cron` | Scheduled job (`schedule` required) |
| `keyvalue` | Managed Key Value (Redis-compatible); alias **`redis`** accepted in Blueprints |

## Runtimes

Common `runtime` values: **`node`**, **`python`**, **`go`**, **`ruby`**, **`rust`**, **`elixir`**, **`docker`**, **`image`**, **`static`**.

- **`docker`**: Build from `Dockerfile` (see `dockerfilePath`, `dockerContext`, `dockerCommand`).
- **`image`**: Run a prebuilt container image (registry + optional `registryCredential`).
- **`static`**: Static site; requires `staticPublishPath` and build output paths (see references).

## Cross-Service Wiring

Env vars under `envVars` (and analogous patterns in groups) can pull values from other resources instead of hardcoding secrets.

### `fromDatabase`

Reference a database in `databases:` by `name`. Properties include:

- `connectionString`, `host`, `port`, `user`, `password`, `database`

### `fromService`

Reference a service by `name`. Typical properties:

- `host`, `port`, `hostport`, `connectionString`, `envVarKey`

Which properties are valid depends on target service type (e.g. Key Value vs `pserv`). See `references/wiring-patterns.md`.

### `fromGroup`

Attach shared vars from `envVarGroups` (by group `name`).

### Other env var keys

- **`value`**: Literal string.
- **`generateValue`**: Let Render generate a random secret (password/API key).
- **`sync`**: Set `sync: false` for secrets that should not sync from repo on every update (see edge cases in wiring reference).

Full patterns and combinations: `references/wiring-patterns.md`.

## Projects and Environments

For multi-service apps, use the **`projects`/`environments`** pattern instead of flat top-level `services`/`databases`. This groups all related resources into a single Render project, supports multiple environments (production, staging), and enables environment-scoped configuration.

```yaml
projects:
  - name: my-app
    environments:
      - name: production
        services:
          - type: web
            name: api
            runtime: node
            plan: standard
            buildCommand: npm ci && npm run build
            startCommand: npm start
            envVars:
              - key: DATABASE_URL
                fromDatabase:
                  name: db
                  property: connectionString
              - key: REDIS_URL
                fromService:
                  type: keyvalue
                  name: cache
                  property: connectionString
              - key: API_SECRET
                sync: false

          - type: worker
            name: jobs
            runtime: node
            plan: starter
            buildCommand: npm ci
            startCommand: node worker.js
            envVars:
              - key: DATABASE_URL
                fromDatabase:
                  name: db
                  property: connectionString
              - key: REDIS_URL
                fromService:
                  type: keyvalue
                  name: cache
                  property: connectionString

          - type: keyvalue
            name: cache
            plan: starter
            maxmemoryPolicy: noeviction
            ipAllowList:
              - source: 0.0.0.0/0
                description: everywhere

        databases:
          - name: db
            plan: starter
```

Key rules:

- Each environment owns its `services` and `databases` lists.
- Do not define the same resource at both the root level and inside an environment.
- `envVarGroups` can be scoped to a project environment or shared across the workspace.
- Environment isolation (Professional+) can block cross-environment private network traffic.

For single-service apps, flat top-level `services`/`databases` is fine. Reach for the projects pattern when you have multiple services, need staging/production separation, or want environment-scoped env groups.

## Preview Environments

Top-level `previews` controls PR previews:

- **`previews.generation`**: `off` (default), `manual`, or `automatic`
- **`previews.expireAfterDays`**: Auto-delete preview stacks after N days

Services can override preview behavior (e.g. service-level `previews.generation`). Limitations: autoscaling behavior, `sync: false` vars, `previewPlan` / flexible instance constraints—see `references/preview-environments.md`.

## Validation

```bash
render blueprints validate
```

Requires **Render CLI v2.7.0+**. Run from the repo root (or pass the appropriate path options your CLI version supports). Fix schema and semantic errors before merging Blueprint changes.

Official schema: `https://render.com/schema/render.yaml.json`

## Immutable Fields

**CRITICAL:** Some fields cannot change after the resource is created. Edits may be rejected or require replacement resources.

### Services

- **`type`**: Cannot change (e.g. web → worker).
- **`runtime`**: Cannot change (e.g. node → docker).

### Databases

Cannot change after creation:

- `name` (logical Blueprint/database identifier in this context)
- `databaseName`
- `user`
- `region`
- `postgresMajorVersion`

Plan other fields (disk, HA, replicas) carefully up front; consult Render docs for fields that can scale vs require recreation.

## Key Fields (Quick Map)

| Area | Fields |
|------|--------|
| Plans | `plan`, `previewPlan` (previews), database `plan` |
| Build/run | `buildCommand`, `startCommand`, `preDeployCommand`, `rootDir` |
| Deploy | `autoDeployTrigger`: `commit`, `checksPass`, or `off` |
| Lifecycle | `maxShutdownDelaySeconds`: 1–300, default **30** |
| HTTP | `healthCheckPath`, `domains` |
| Storage | `disk` (`name`, `mountPath`, `sizeGB`) |
| Scale | `scaling` / `numInstances` (see references) |
| Monorepo | `buildFilter` (`paths`, `ignoredPaths`) |
| Docker | `dockerfilePath`, `dockerContext`, `dockerCommand`, `registryCredential` |

Deprecated names to avoid: `env` (use `runtime`), `redis` (use `keyvalue`), `autoDeploy` (use `autoDeployTrigger`), `pullRequestPreviewsEnabled` (use `previews.generation`). Details: `references/common-mistakes.md`.

## References

| Document | Contents |
|----------|----------|
| `references/field-reference.md` | YAML fields by service type, database, groups, projects, previews, scaling, disk, static, Key Value |
| `references/wiring-patterns.md` | `fromDatabase` / `fromService` / `fromGroup` examples, `sync: false`, `generateValue`, combinations |
| `references/common-mistakes.md` | Branch + previews, `buildFilter`, replicas, duplicates, preview plans, wiring mistakes |
| `references/preview-environments.md` | `previews.generation`, expiry, overrides, `previewPlan`, disks, PR workflow |

## Related Skills

- **render-deploy** — Deploy flows, Blueprint vs direct create, MCP/deeplinks
- **render-env-vars** — Env var strategy, secrets, Dashboard vs Blueprint
- **render-docker** — Dockerfile-backed services and image runtime nuances

Referenced files: 4

View saved version →

---
name: render-cli
description: >-
  Installs and uses the Render CLI for deploys, logs, SSH, psql, Blueprint
  validation, and automation. Use when the user needs to run Render CLI
  commands, script deploys in CI/CD, authenticate with an API key, query
  services non-interactively, or troubleshoot CLI auth issues.
  Trigger terms: render CLI, render login, render deploys, render logs,
  render ssh, render psql, render blueprints validate, render skills,
  RENDER_API_KEY, non-interactive, CI/CD deploy.
license: MIT
compatibility: Render CLI v2.7.0+ (Homebrew, Linux/macOS, direct download)
metadata:
  author: Render
  version: "1.0.0"
  category: operations
---

# Render CLI

The Render CLI manages services, databases, and deployments from the terminal. Supports interactive use, non-interactive scripting, and CI/CD automation.

## When to Use

- **Deploying** a service from the terminal or CI/CD
- **Tailing logs** in real time
- **Opening psql** to a Render Postgres database
- **SSHing** into a running service or launching an ephemeral shell
- **Validating** a `render.yaml` Blueprint
- **Scripting** Render operations in CI/CD pipelines
- **Installing** agent skills for AI coding tools

## Installation

| Method | Command |
|--------|---------|
| **Homebrew** | `brew update && brew install render` |
| **Linux/macOS** | `curl -fsSL https://raw.githubusercontent.com/render-oss/cli/refs/heads/main/bin/install.sh \| sh` |
| **Direct download** | [GitHub releases](https://github.com/render-oss/cli/releases/) |
| **Build from source** | `git clone git@github.com:render-oss/cli.git && cd cli && go build -o render` |

After install, run `render` with no arguments to confirm.

## Authentication

### Interactive (local dev)

```bash
render login
```

Opens the browser to generate a CLI token. Token is saved to `~/.render/cli.yaml`. Tokens expire periodically—re-run `render login` when prompted.

### Non-interactive (CI/CD)

```bash
export RENDER_API_KEY=rnd_...
```

API keys do not expire. Generate one from **Account Settings > API Keys** in the Dashboard. The API key takes precedence over CLI tokens when set.

Set the active workspace:

```bash
render workspace set
```

## Command Reference

### Core commands

| Command | Purpose | Key flags |
|---------|---------|-----------|
| `render login` | Authenticate via browser | — |
| `render workspace set` | Set active workspace | — |
| `render services` | List all services and datastores | `-o json` for scripting |
| `render deploys create [SVC]` | Trigger a deploy | `--wait`, `--commit SHA`, `--image URL` |
| `render deploys list [SVC]` | List deploys for a service | `-o json` |
| `render logs -r [SVC]` | View logs | `--tail` for streaming |
| `render psql [DB]` | Open psql session | `-c "SQL"`, `-o json`, `-- --csv` |
| `render ssh [SVC]` | SSH into running instance | `--ephemeral` / `-e` for isolated shell |
| `render blueprints validate` | Validate `render.yaml` | Defaults to `./render.yaml` |
| `render skills [install\|update\|list]` | Manage agent skills | — |
| `render workspaces` | List workspaces | `-o json` |

### Non-interactive mode

For CI/CD and scripts, always set:

| Flag | Purpose |
|------|---------|
| `-o json` (or `yaml`, `text`) | Machine-readable output |
| `--confirm` | Skip confirmation prompts |

Output format precedence: `--output` flag > `RENDER_OUTPUT` env var > auto-detect (TTY → interactive, pipe → text).

```bash
export RENDER_OUTPUT=json
render services --confirm
```

### Deploy patterns

```bash
# Deploy and wait for completion (exits non-zero on failure)
render deploys create srv-xxx --wait --confirm -o json

# Deploy a specific commit
render deploys create srv-xxx --commit abc123 --wait --confirm

# Deploy a specific Docker image
render deploys create srv-xxx --image ghcr.io/org/app:v1.2.3 --wait --confirm
```

### Database queries

```bash
# Single query, JSON output
render psql db-xxx -c "SELECT NOW();" -o json

# CSV output via psql passthrough
render psql db-xxx -c "SELECT id, email FROM users;" -o text -- --csv
```

## CI/CD Example (GitHub Actions)

```yaml
name: Deploy to Render
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install Render CLI
        run: |
          curl -L https://github.com/render-oss/cli/releases/download/v1.1.0/cli_1.1.0_linux_amd64.zip -o render.zip
          unzip render.zip
          sudo mv cli_v1.1.0 /usr/local/bin/render
      - name: Deploy
        env:
          RENDER_API_KEY: ${{ secrets.RENDER_API_KEY }}
        run: render deploys create ${{ secrets.RENDER_SERVICE_ID }} --wait --confirm -o json
```

Pin to a specific CLI version in CI to avoid breaking changes.

## Local Config

Config file: `~/.render/cli.yaml`

Override with `RENDER_CLI_CONFIG_PATH` env var.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Token expired | Re-run `render login` |
| Wrong workspace | Run `render workspace set` to switch |
| Missing `--confirm` in CI | Add `--confirm` to skip interactive prompts |
| Using `--output interactive` in CI | Use `-o json` or `-o text` in non-TTY environments |
| Deploying without `--wait` in CI | Add `--wait` so the job fails on deploy failure |

## References

| Document | Contents |
|----------|----------|
| `references/command-cheatsheet.md` | Full command list with flags, output examples, and scripting patterns |

## Related Skills

- **render-deploy** — End-to-end deploy flows, MCP operations, Dashboard deeplinks
- **render-blueprints** — `render.yaml` authoring and validation
- **render-postgres** — Database connections, `render psql` usage
- **render-debug** — Using `render logs` and `render ssh` for troubleshooting

Referenced files: 1

View saved version →

---
name: render-cron-jobs
description: >-
  Configures and troubleshoots scheduled tasks on Render using cron job
  services. Use when the user needs to run something on a schedule, write a
  cron expression, set up a periodic job, migrate from Heroku Scheduler,
  choose between cron jobs and background workers, or fix a cron that isn't
  firing.
  Trigger terms: cron job, scheduled task, periodic job, cron expression,
  schedule, run every, timer, Heroku Scheduler migration.
license: MIT
compatibility: Render cron job services
metadata:
  author: Render
  version: "1.0.0"
  category: compute
---

# Render Cron Jobs

This skill covers **Cron Job** services on Render: how schedules run, what the platform guarantees, and how they differ from workers and workflows. Pair it with Blueprint and deploy skills when authoring `render.yaml` or Dashboard settings.

## When to Use

- **Scheduled** work that **starts on a cron**, runs a command, and **exits** when finished
- Choosing between **cron**, **background worker**, or **workflow** for periodic or long-running jobs
- **Blueprint** fields for `type: cron`, `schedule`, and commands
- **Constraints**: no disk, single concurrent run, 12-hour max duration, private-network **outbound** only
- **UTC** scheduling pitfalls (expressions are **not** local time)

Expression cheat sheets, framework `startCommand` examples, and Heroku Scheduler migration mapping live under `references/`.

## Configuration

- **Schedule**: a **cron expression evaluated in UTC**, not the team’s local timezone. All times in the Dashboard and Blueprints are UTC.
- **Command**: any valid **Linux shell command** or **bash script** path. The process must **exit** when work is done—**billing is based on run duration** (prorated by the second).
- **Source**:
  - **Git repository** — Render **builds on push** (same deploy model as other repo-backed services); the built artifact runs on each scheduled invocation.
  - **Prebuilt Docker image** — the image is **pulled before each run** and is **not retained between runs** (no warm cache of the image layer set across invocations in the same way as a long-lived service).

## Constraints

- **No persistent disk** — cron job services **cannot** provision or attach Render persistent disks; plan for object storage or databases instead.
- **Single-run guarantee** — at most **one active run** per cron service at a time. A new scheduled tick does not start a second overlapping instance.
- **Maximum run length**: **12 hours** per invocation.
- **Pricing**: **$1/month minimum** per cron job service; usage is **prorated by the second** beyond plan/minimum rules that apply to your account.
- **Private network**: cron jobs **can send** traffic **to** other services on the private network; they **cannot receive** inbound private-network connections (no internal hostname for accepting traffic from other services).

## Execution Behavior

- **Manual “Trigger Run”** while a run is **active**: Render **cancels** the active run, then **starts** a new one.
- **New Git build / deploy** does **not** affect a run already **in progress**—the in-flight process keeps using the revision it started with until it exits.
- **Docker-based crons**: the image is **pulled fresh for each run**; do not assume layer or image reuse across invocations like a continuously running container.
- **UTC everywhere**: cron expressions and “midnight” in docs mean **UTC**. A common mistake is copying a local-time schedule into the expression without converting to UTC.

## Cron vs Worker vs Workflow

| Need | Use | Why |
|------|-----|-----|
| Periodic task **under 12h** | **Cron Job** | Scheduled, simple, exits when done |
| **Continuous** job processing | **Background Worker** | Always running, polls a queue |
| Periodic but **over 12h** | **Background Worker** | No 12h cron run ceiling |
| **Scheduled parallel** compute | **Cron Job + Workflow** | Cron triggers workflow runs on a schedule; workflows fan out or orchestrate parallel steps |

## Blueprint Configuration

Cron services use **`type: cron`** with a **`schedule`** and the usual build/start and env wiring:

```yaml
services:
  - type: cron
    name: nightly-cleanup
    schedule: "0 * * * *" # hourly at minute 0 — must be quoted in YAML
    buildCommand: pip install -r requirements.txt
    startCommand: python cleanup.py
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: my-db
          property: connectionString
```

- **`schedule`**: standard five-field cron (`minute hour day-of-month month day-of-week`), **UTC**.
- **`buildCommand`** / **`startCommand`**: same roles as other non-Docker services; Docker images use image + start command as configured for image-backed crons.
- **`envVars`**: same patterns as web services and workers (secrets, linked databases, etc.).

**YAML note**: the `schedule` value **must be quoted** so characters like `*` are not parsed as YAML aliases or flow syntax.

## Common Patterns

- **Database cleanup** — archive or delete stale rows on a schedule
- **Report generation** — build CSV/PDF and upload to object storage or email
- **External API sync** — pull or push batches on an interval
- **Cache warming** — hit endpoints or rebuild caches before peak traffic
- **Scheduled emails** — digest or reminder sends driven by cron + mail/API

## References

| Topic | File |
|--------|------|
| Expression examples, framework commands, errors, env vars | `references/cron-patterns.md` |
| Heroku Scheduler → Render mapping, blueprint example | `references/migration-from-scheduler.md` |

## Related Skills

- **render-deploy** — First-time deploy, service creation, Dashboard flow
- **render-blueprints** — Full `render.yaml` schema, previews, common mistakes
- **render-background-workers** — Long-lived processes, queues, no 12h cap
- **render-workflows** — Orchestrated and parallel jobs, often triggered on a schedule from cron

Referenced files: 2

View saved version →

---
name: render-debug
description: Debug failed Render deployments by analyzing logs, metrics, and database state. Identifies errors (missing env vars, port binding, OOM, etc.) and suggests fixes. Use when deployments fail, services won't start, or users mention errors, logs, or debugging.
license: MIT
compatibility: Requires Render MCP tools or CLI
metadata:
  author: Render
  version: "1.1.0"
  category: debugging
---

# Debug Render Deployments

Analyze deployment failures using logs, metrics, and database queries. Identify root causes and apply fixes.

## When to Use This Skill

Activate this skill when:
- Deployment fails on Render
- Service won't start or keeps crashing
- User mentions errors, logs, or debugging
- Health checks are timing out
- Application errors in production
- Performance issues (slow responses)
- Database connection problems

## Prerequisites

**MCP tools (preferred):** Test with `list_services()` - provides structured data

**CLI (fallback):** `render --version` - use if MCP tools unavailable

**Authentication:** If you installed the Render plugin (Cursor, Codex, Claude Code), it provides OAuth for MCP — complete the OAuth prompt. For manual MCP clients, use a Render API key. For CLI, verify with `render whoami -o json`.

**Workspace:** `get_selected_workspace()` or `render workspace current -o json`

> **Note:** MCP tools require the Render MCP server. If unavailable, use the CLI for logs and deploy status; metrics and structured database queries require MCP.

## MCP Setup

If `list_services()` fails, set up the Render MCP server. For detailed per-tool walkthroughs, see **render-mcp**.

**Plugin setup:** If the Render plugin is installed, complete Render OAuth when prompted, then reload your tool and retry `list_services()`.

**Manual MCP setup:** Add the Render MCP server to your AI tool's MCP config:
- **URL:** `https://mcp.render.com/mcp`
- **Auth header:** `Authorization: Bearer <YOUR_API_KEY>`
- **API key:** `https://dashboard.render.com/u/*/settings#api-keys`

After configuring, restart your tool and retry `list_services()`. Then set your workspace with `list_workspaces()` / `get_selected_workspace()`.

---

## Debugging Workflow

### Step 1: Identify Failed Service

```
list_services()
```

If MCP isn't configured, ask whether to set it up (preferred) or continue with CLI. Then proceed.

Look for services with failed status. Get details:

```
get_service(serviceId: "<id>")
```

### Step 2: Retrieve Logs

**Build/Deploy Logs (most failures):**
```
list_logs(resource: ["<service-id>"], type: ["build"], limit: 200)
```

**Runtime Error Logs:**
```
list_logs(resource: ["<service-id>"], level: ["error"], limit: 100)
```

**Search for Specific Errors:**
```
list_logs(resource: ["<service-id>"], text: ["KeyError", "ECONNREFUSED"], limit: 50)
```

**HTTP Error Logs:**
```
list_logs(resource: ["<service-id>"], statusCode: ["500", "502", "503"], limit: 50)
```

### Step 3: Analyze Error Patterns

Match log errors against known patterns:

| Error | Log Pattern | Common Fix |
|-------|-------------|------------|
| **MISSING_ENV_VAR** | `KeyError`, `not defined` | Add to render.yaml or `update_environment_variables` |
| **PORT_BINDING** | `EADDRINUSE` | Use `0.0.0.0:$PORT` |
| **MISSING_DEPENDENCY** | `Cannot find module` | Add to package.json/requirements.txt |
| **DATABASE_CONNECTION** | `ECONNREFUSED :5432` | Check DATABASE_URL, DB status |
| **HEALTH_CHECK** | `Health check timeout` | Add /health endpoint, check port binding |
| **OUT_OF_MEMORY** | `heap out of memory`, exit 137 | Optimize memory or upgrade plan |
| **BUILD_FAILURE** | `Command failed` | Fix build command or dependencies |

Full error catalog: [references/error-patterns.md](references/error-patterns.md)

**If errors repeat across deploys:** Switch from incremental fixes to a broader sweep. Scan the codebase/config for all likely causes in that error class (related env vars, build config, dependencies, or type errors) and address them together before the next redeploy.

### Step 4: Check Metrics (Performance Issues)

For crashes, slow responses, or resource issues:

```
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["cpu_usage", "memory_usage", "memory_limit"]
)
```

```
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_latency"],
  httpLatencyQuantile: 0.95
)
```

Detailed metrics guide: [references/metrics-debugging.md](references/metrics-debugging.md)

### Step 5: Debug Database Issues

For database-related errors:

```
# Check database status
list_postgres_instances()

# Check connections
get_metrics(resourceId: "<postgres-id>", metricTypes: ["active_connections"])

# Query directly
query_render_postgres(
  postgresId: "<postgres-id>",
  sql: "SELECT state, count(*) FROM pg_stat_activity GROUP BY state"
)
```

Detailed database guide: [references/database-debugging.md](references/database-debugging.md)

### Step 6: Apply Fix

**For environment variables:**
```
update_environment_variables(
  serviceId: "<service-id>",
  envVars: [{"key": "MISSING_VAR", "value": "value"}]
)
```

**For code changes:**
1. Edit the source file
2. Commit and push
3. Deploy triggers automatically (if auto-deploy enabled)

### Step 7: Verify Fix

```
# Check deploy status
list_deploys(serviceId: "<service-id>", limit: 1)

# Check for new errors
list_logs(resource: ["<service-id>"], level: ["error"], limit: 20)

# Check metrics
get_metrics(resourceId: "<service-id>", metricTypes: ["http_request_count"])
```

---

## Quick Workflows

Pre-built debugging sequences for common scenarios:

| Scenario | Workflow |
|----------|----------|
| Deploy failed | `list_deploys` → `list_logs(type: build)` → fix → redeploy |
| App crashing | `list_logs(level: error)` → `get_metrics(memory)` → fix |
| App slow | `get_metrics(http_latency)` → `get_metrics(cpu)` → `query_postgres` |
| DB connection | `list_postgres` → `get_metrics(connections)` → `query_postgres` |
| Post-deploy check | `list_deploys` → `list_logs(error)` → `get_metrics` |

Detailed workflows: [references/quick-workflows.md](references/quick-workflows.md)

---

## Quick Reference

### MCP Tools

```
# Service Discovery
list_services()
get_service(serviceId: "<id>")
list_postgres_instances()

# Logs
list_logs(resource: ["<id>"], level: ["error"], limit: 100)
list_logs(resource: ["<id>"], type: ["build"], limit: 200)
list_logs(resource: ["<id>"], text: ["search"], limit: 50)

# Metrics
get_metrics(resourceId: "<id>", metricTypes: ["cpu_usage", "memory_usage"])
get_metrics(resourceId: "<id>", metricTypes: ["http_latency"], httpLatencyQuantile: 0.95)

# Database
query_render_postgres(postgresId: "<id>", sql: "SELECT ...")

# Deployments
list_deploys(serviceId: "<id>", limit: 5)

# Environment Variables
update_environment_variables(serviceId: "<id>", envVars: [{key, value}])
```

### CLI Commands (Fallback)

```bash
render services -o json
render logs -r <service-id> --level error -o json
render logs -r <service-id> --tail -o text
render deploys create <service-id> --wait
```

---

## References

- **Error patterns:** [references/error-patterns.md](references/error-patterns.md)
- **Metrics debugging:** [references/metrics-debugging.md](references/metrics-debugging.md)
- **Database debugging:** [references/database-debugging.md](references/database-debugging.md)
- **Quick workflows:** [references/quick-workflows.md](references/quick-workflows.md)
- **Log analysis:** [references/log-analysis.md](references/log-analysis.md)
- **Troubleshooting:** [references/troubleshooting.md](references/troubleshooting.md)

## Related Skills

- **render-deploy** — Deploy new applications to Render
- **render-monitor** — Ongoing service health monitoring
- **render-mcp** — MCP server setup and tool catalog

Referenced files: 6

View saved version →

---
name: render-deploy
description: Deploy applications to Render by analyzing codebases, generating render.yaml Blueprints, and providing Dashboard deeplinks. Use when the user wants to deploy, host, publish, or set up their application on Render's cloud platform.
license: MIT
compatibility: Requires a Git repository on GitHub, GitLab, or Bitbucket for Blueprint/MCP flows. Blueprint can reference a prebuilt image but render.yaml must live in the repo. Render CLI recommended for Blueprint validation; MCP or CLI required for operations.
metadata:
  author: Render
  version: "1.1.0"
  category: deployment
---

# Deploy to Render

Render supports **Git-backed** services and **prebuilt Docker image** services.

This skill covers **Git-backed** flows:
1. **Blueprint Method** - Generate render.yaml for Infrastructure-as-Code deployments
2. **Direct Creation** - Create services instantly via MCP tools

Blueprints can also run a **prebuilt Docker image** by using `runtime: image`, but the `render.yaml` still must live in a Git repo.

If there is no Git remote, stop and ask the user to either:
- Create/push a Git remote (can be minimal if only the Blueprint is needed), or
- Use the Render Dashboard/API to deploy a prebuilt Docker image (MCP cannot create image-backed services).

## When to Use This Skill

Activate this skill when users want to:
- Deploy an application to Render
- Create a render.yaml Blueprint file
- Set up Render deployment for their project
- Host or publish their application on Render's cloud platform
- Create databases, cron jobs, or other Render resources

## Happy Path (New Users)

Use this short prompt sequence before deep analysis to reduce friction:
1. Ask whether they want to deploy from a Git repo or a prebuilt Docker image.
2. Ask whether Render should provision everything the app needs (based on what seems likely from the user's description) or only the app while they bring their own infra. If dependencies are unclear, ask a short follow-up to confirm whether they need a database, workers, cron, or other services.

Then proceed with the appropriate method below.

## Choose Your Source Path

**Git Repo Path:** Required for both Blueprint and Direct Creation. The repo must be pushed to GitHub, GitLab, or Bitbucket.

**Prebuilt Docker Image Path:** Supported by Render via image-backed services. This is **not** supported by MCP; use the Dashboard/API. Ask for:
- Image URL (registry + tag)
- Registry auth (if private)
- Service type (web/worker) and port

If the user chooses a Docker image, guide them to the Render Dashboard image deploy flow or ask them to add a Git remote (so you can use a Blueprint with `runtime: image`).

## Choose Your Deployment Method (Git Repo)

Both methods require a Git repository pushed to GitHub, GitLab, or Bitbucket. (If using `runtime: image`, the repo can be minimal and only contain `render.yaml`.)

| Method | Best For | Pros |
|--------|----------|------|
| **Blueprint** | Multi-service apps, IaC workflows | Version controlled, reproducible, supports complex setups |
| **Direct Creation** | Single services, quick deployments | Instant creation, no render.yaml file needed |

### Method Selection Heuristic

Use this decision rule by default unless the user requests a specific method. Analyze the codebase first; only ask if deployment intent is unclear (e.g., DB, workers, cron).

**Use Direct Creation (MCP) when ALL are true:**
- Single service (one web app or one static site)
- No separate worker/cron services
- No attached databases or Key Value
- Simple env vars only (no shared env groups)
If this path fits and MCP isn't configured yet, stop and guide MCP setup before proceeding.

**Use Blueprint when ANY are true:**
- Multiple services (web + worker, API + frontend, etc.)
- Databases, Redis/Key Value, or other datastores are required
- Cron jobs, background workers, or private services
- You want reproducible IaC or a render.yaml committed to the repo
- Monorepo or multi-env setup that needs consistent configuration

If unsure, ask a quick clarifying question, but default to Blueprint for safety. For a single service, strongly prefer Direct Creation via MCP and guide MCP setup if needed.

## Prerequisites Check

When starting a deployment, verify these requirements in order:

**1. Confirm Source Path (Git vs Docker)**

If using Git-based methods (Blueprint or Direct Creation), the repo must be pushed to GitHub/GitLab/Bitbucket. Blueprints that reference a prebuilt image still require a Git repo with `render.yaml`.

```bash
git remote -v
```

- If no remote exists, stop and ask the user to create/push a remote **or** switch to Docker image deploy.

**2. Check MCP Tools Availability (Preferred for Single-Service)**

MCP tools provide the best experience. Check if available by attempting:
```
list_services()
```

If MCP tools are available, you can skip CLI installation for most operations.

**3. Check Render CLI Installation (for Blueprint validation)**
```bash
render --version
```
If not installed, offer to install:
- macOS: `brew install render`
- Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh`

**4. MCP Setup (if MCP isn't configured)**

If `list_services()` fails, set up the Render MCP server. For detailed per-tool walkthroughs, see **render-mcp**.

**Plugin setup:** If the Render plugin is installed, complete Render OAuth when prompted, then reload your tool and retry `list_services()`.

**Manual MCP setup:** Add the Render MCP server to your AI tool's MCP config:
- **URL:** `https://mcp.render.com/mcp`
- **Auth header:** `Authorization: Bearer <YOUR_API_KEY>`
- **API key:** `https://dashboard.render.com/u/*/settings#api-keys`

After configuring, restart your tool and retry `list_services()`. Then set your workspace with `list_workspaces()` / `get_selected_workspace()`.

**5. Check Authentication (CLI fallback only)**

If MCP isn't available, use the CLI instead and verify you can access your account:
```bash
# Check if user is logged in (use -o json for non-interactive mode)
render whoami -o json
```

If `render whoami` fails or returns empty data, the CLI is not authenticated. The CLI won't always prompt automatically, so explicitly prompt the user to authenticate:

If neither is configured, ask user which method they prefer:
- **API Key (CLI)**: `export RENDER_API_KEY="rnd_xxxxx"` (Get from https://dashboard.render.com/u/*/settings#api-keys)
- **Login**: `render login` (Opens browser for OAuth)

**6. Check Workspace Context**

Verify the active workspace:
```
get_selected_workspace()
```

Or via CLI:
```bash
render workspace current -o json
```

To list available workspaces:
```
list_workspaces()
```

If user needs to switch workspaces, they must do so via Dashboard or CLI (`render workspace set`).

Once prerequisites are met, proceed with deployment workflow.

---

# Method 1: Blueprint Deployment (Recommended for Complex Apps)

## Blueprint Workflow

### Step 1: Analyze Codebase

Analyze the codebase to determine framework/runtime, build and start commands, required env vars, datastores, and port binding. Use the detailed checklists in [references/codebase-analysis.md](references/codebase-analysis.md).

### Step 2: Generate render.yaml

Create a `render.yaml` Blueprint file following the Blueprint specification.

Complete specification: [references/blueprint-spec.md](references/blueprint-spec.md)

**Key Points:**
- Always use `plan: free` unless user specifies otherwise
- Include ALL environment variables the app needs
- Mark secrets with `sync: false` (user fills these in Dashboard)
- Use appropriate service type: `web`, `worker`, `cron`, `static`, or `pserv`
- Use appropriate runtime: [references/runtimes.md](references/runtimes.md)

**Basic Structure:**
```yaml
services:
  - type: web
    name: my-app
    runtime: node
    plan: free
    buildCommand: npm ci
    startCommand: npm start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: postgres
          property: connectionString
      - key: JWT_SECRET
        sync: false  # User fills in Dashboard

databases:
  - name: postgres
    databaseName: myapp_db
    plan: free
```

**Service Types:**
- `web`: HTTP services, APIs, web applications (publicly accessible)
- `worker`: Background job processors (not publicly accessible)
- `cron`: Scheduled tasks that run on a cron schedule
- `static`: Static sites (HTML/CSS/JS served via CDN)
- `pserv`: Private services (internal only, within same account)

Service type details: [references/service-types.md](references/service-types.md)
Runtime options: [references/runtimes.md](references/runtimes.md)
Template examples: [assets/](assets/)

### Step 2.5: Immediate Next Steps (Always Provide)

After creating `render.yaml`, always give the user a short, explicit checklist and run validation immediately when the CLI is available:
1. **Authenticate (CLI)**: run `render whoami -o json` (if not logged in, run `render login` or set `RENDER_API_KEY`)
2. **Validate (recommended)**: run `render blueprints validate`
   - If the CLI isn't installed, offer to install it and provide the command.
3. **Commit + push**: `git add render.yaml && git commit -m "Add Render deployment configuration" && git push origin main`
4. **Open Dashboard**: Use the Blueprint deeplink and complete Git OAuth if prompted
5. **Fill secrets**: Set env vars marked `sync: false`
6. **Deploy**: Click "Apply" and monitor the deploy

### Step 3: Validate Configuration

Validate the render.yaml file to catch errors before deployment. If the CLI is installed, run the commands directly; only prompt the user if the CLI is missing:

```bash
render whoami -o json  # Ensure CLI is authenticated (won't always prompt)
render blueprints validate
```

Fix any validation errors before proceeding. Common issues:
- Missing required fields (`name`, `type`, `runtime`)
- Invalid runtime values
- Incorrect YAML syntax
- Invalid environment variable references

Configuration guide: [references/configuration-guide.md](references/configuration-guide.md)

### Step 4: Commit and Push

**IMPORTANT:** You must merge the `render.yaml` file into your repository before deploying.

Ensure the `render.yaml` file is committed and pushed to your Git remote:

```bash
git add render.yaml
git commit -m "Add Render deployment configuration"
git push origin main
```

If there is no Git remote yet, stop here and guide the user to create a GitHub/GitLab/Bitbucket repo, add it as `origin`, and push before continuing.

**Why this matters:** The Dashboard deeplink will read the render.yaml from your repository. If the file isn't merged and pushed, Render won't find the configuration and deployment will fail.

Verify the file is in your remote repository before proceeding to the next step.

### Step 5: Generate Deeplink

Get the Git repository URL:

```bash
git remote get-url origin
```

This will return a URL from your Git provider. **If the URL is SSH format, convert it to HTTPS:**

| SSH Format | HTTPS Format |
|------------|--------------|
| `git@github.com:user/repo.git` | `https://github.com/user/repo` |
| `git@gitlab.com:user/repo.git` | `https://gitlab.com/user/repo` |
| `git@bitbucket.org:user/repo.git` | `https://bitbucket.org/user/repo` |

**Conversion pattern:** Replace `git@<host>:` with `https://<host>/` and remove `.git` suffix.

Format the Dashboard deeplink using the HTTPS repository URL:
```
https://dashboard.render.com/blueprint/new?repo=<REPOSITORY_URL>
```

Example:
```
https://dashboard.render.com/blueprint/new?repo=https://github.com/username/repo-name
```

### Step 6: Guide User

**CRITICAL:** Ensure the user has merged and pushed the render.yaml file to their repository before clicking the deeplink. If the file isn't in the repository, Render cannot read the Blueprint configuration and deployment will fail.

Provide the deeplink to the user with these instructions:

1. **Verify render.yaml is merged** - Confirm the file exists in your repository on GitHub/GitLab/Bitbucket
2. Click the deeplink to open Render Dashboard
3. Complete Git provider OAuth if prompted
4. Name the Blueprint (or use default from render.yaml)
5. Fill in secret environment variables (marked with `sync: false`)
6. Review services and databases configuration
7. Click "Apply" to deploy

The deployment will begin automatically. Users can monitor progress in the Render Dashboard.

### Step 7: Verify Deployment

After the user deploys via Dashboard, verify everything is working.

**Check deployment status via MCP:**
```
list_deploys(serviceId: "<service-id>", limit: 1)
```
Look for `status: "live"` to confirm successful deployment.

**Check for runtime errors (wait 2-3 minutes after deploy):**
```
list_logs(resource: ["<service-id>"], level: ["error"], limit: 20)
```

**Check service health metrics:**
```
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_request_count", "cpu_usage", "memory_usage"]
)
```

If errors are found, proceed to the **Post-deploy verification and basic triage** section below.

---

# Method 2: Direct Service Creation (Quick Single-Service Deployments)

For simple deployments without Infrastructure-as-Code, create services directly via MCP tools.

## When to Use Direct Creation

- Single web service or static site
- Quick prototypes or demos
- When you don't need a render.yaml file in your repo
- Adding databases or cron jobs to existing projects

## Prerequisites for Direct Creation

**Repository must be pushed to a Git provider.** Render clones your repository to build and deploy services.

```bash
git remote -v  # Verify remote exists
git push origin main  # Ensure code is pushed
```

Supported providers: GitHub, GitLab, Bitbucket

If no remote exists, stop and ask the user to create/push a remote or switch to Docker image deploy.

**Note:** MCP does not support creating image-backed services. Use the Dashboard/API for prebuilt Docker image deploys.

## Direct Creation Workflow

Use the concise steps below, and refer to [references/direct-creation.md](references/direct-creation.md) for full MCP command examples and follow-on configuration.

### Step 1: Analyze Codebase
Use [references/codebase-analysis.md](references/codebase-analysis.md) to determine runtime, build/start commands, env vars, and datastores.

### Step 2: Create Resources via MCP
Create the service (web or static) and any required databases or key-value stores. See [references/direct-creation.md](references/direct-creation.md).

If MCP returns an error about missing Git credentials or repo access, stop and guide the user to connect their Git provider in the Render Dashboard, then retry.

### Step 3: Configure Environment Variables
Add required env vars via MCP after creation. See [references/direct-creation.md](references/direct-creation.md).

Remind the user that secrets can be set in the Dashboard if they prefer not to pass them via MCP.

### Step 4: Verify Deployment
Check deploy status, logs, and metrics. See [references/direct-creation.md](references/direct-creation.md).

---

For service discovery, configuration details, quick commands, and common issues, see [references/deployment-details.md](references/deployment-details.md).

---

# Post-deploy verification and basic triage (All Methods)

Keep this short and repeatable. If any check fails, fix it before redeploying.

1. Confirm the latest deploy is `live` and serving traffic
2. Hit the health endpoint (or root) and verify a 200 response
3. Scan recent error logs for a clear failure signature
4. Verify required env vars and port binding (`0.0.0.0:$PORT`)

Detailed checklist and commands: [references/post-deploy-checks.md](references/post-deploy-checks.md)

If the service fails to start or health checks time out, use the basic triage guide:
[references/troubleshooting-basics.md](references/troubleshooting-basics.md)

Optional: If you need deeper diagnostics (metrics/DB checks/error catalog), suggest installing the
`render-debug` skill. It is not required for the core deploy flow.

Referenced files: 16

View saved version →

---
name: render-disks
description: >-
  Attaches and manages persistent disks on Render services—mount paths, sizing,
  snapshots, file transfers, and single-instance constraints. Use when the user
  needs persistent storage, file uploads, a custom database on disk, CMS media
  storage, or needs to understand why their service can't scale horizontally
  or use zero-downtime deploys.
  Trigger terms: persistent disk, disk, storage, mount path, sizeGB, SSD,
  file uploads, snapshots, disk restore, ephemeral filesystem.
license: MIT
compatibility: Render paid web services, private services, and background workers
metadata:
  author: Render
  version: "1.0.0"
  category: storage
---

# Render Persistent Disks

Persistent disks are high-performance SSDs you attach to a Render service to preserve filesystem changes across deploys and restarts. Without a disk, services have an **ephemeral filesystem**—all local file changes are lost on every deploy.

## When to Use

- Storing **file uploads**, CMS media, or user-generated content
- Running a **self-managed database** (MySQL, MongoDB, ClickHouse) on Render
- Deploying **stateful infrastructure** (Elasticsearch, Kafka, RabbitMQ, Mattermost)
- Understanding **why scaling is blocked** or **zero-downtime deploys are disabled**
- **Restoring data** from an automatic disk snapshot

For managed databases, prefer **Render Postgres** (render-postgres) or **Key Value** (render-keyvalue) over self-managed alternatives on disk.

## Critical Constraints

These constraints affect architecture decisions. Understand them **before** attaching a disk:

| Constraint | Impact |
|------------|--------|
| **Single instance only** | Cannot scale horizontally (`numInstances` must be 1, autoscaling not available) |
| **No zero-downtime deploys** | Old instance stops before new instance starts (brief downtime on each deploy) |
| **Runtime access only** | Disk is not available during `buildCommand` or `preDeployCommand` (those run on separate compute) |
| **Not accessible from other services** | Only the attached service can read/write the disk |
| **Not available on cron jobs** | Attach to a web service, private service, or background worker instead |
| **Not available on one-off jobs** | One-off jobs run on separate compute without disk access |
| **Can increase size, cannot decrease** | Start small and grow as needed |

## Setup

### Dashboard

1. Go to your service's **Disks** page
2. Set the **mount path** (absolute path where persistent data is stored)
3. Choose a **size** in GB
4. Click **Add disk** — triggers a new deploy

### Blueprint

```yaml
services:
  - type: web
    name: cms
    runtime: node
    plan: starter
    region: oregon
    buildCommand: npm ci && npm run build
    startCommand: npm start
    disk:
      name: cms-data
      mountPath: /var/data
      sizeGB: 10
```

## Mount Path

Only files written **under the mount path** are preserved. Everything else remains ephemeral.

| Runtime | Source code path | Example mount path |
|---------|------------------|--------------------|
| Node.js, Python, Ruby, Elixir, Rust | `/opt/render/project/src` | `/opt/render/project/src/uploads` |
| Go | `/opt/render/project/go/src/github.com/<user>/<repo>` | `.../data` |
| Docker | Dockerfile's `WORKDIR` (commonly `/app`) | `/app/storage` |

### Disallowed mount paths

Cannot mount at: `/`, `/opt`, `/opt/render`, `/opt/render/project`, `/opt/render/project/src`, `/home`, `/home/render`, `/etc`, `/etc/secrets`.

Subdirectories of these paths are fine (e.g. `/opt/render/project/src/uploads`).

## Snapshots

- Render creates an **automatic snapshot every 24 hours**
- Snapshots are available for **at least 7 days**
- Restore from the service's **Disks** page in the Dashboard
- **Full restore only** — you cannot restore individual files
- **Destructive** — all changes after the snapshot are lost

**Do not restore snapshots for custom database recovery.** Use database-native backup tools (mysqldump, mongodump) instead—disk snapshots may capture a corrupted database state.

## File Transfers

### SCP (via SSH)

```bash
# Download from service
scp -s YOUR_SERVICE@ssh.YOUR_REGION.render.com:/mount/path/file ./local-file

# Upload to service
scp -s ./local-file YOUR_SERVICE@ssh.YOUR_REGION.render.com:/mount/path/file
```

Requires SSH access enabled for the service.

### Magic-Wormhole

Available on all native runtimes (install manually on Docker):

```bash
# On the service shell
wormhole send /mount/path/file

# On your local machine
wormhole receive
```

## Common Patterns

| Pattern | Service type | Mount path | Notes |
|---------|-------------|------------|-------|
| WordPress / Ghost / CMS | Web Service | `/var/data` or `/app/content` | Media uploads, SQLite |
| Self-managed MySQL | Private Service | `/var/lib/mysql` | Use mysqldump for backups, not disk snapshots |
| File upload API | Web Service | `/opt/render/project/src/uploads` | Single instance constraint |
| Elasticsearch | Private Service | `/usr/share/elasticsearch/data` | Stateful search infrastructure |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Expecting horizontal scaling with a disk | Not possible — disk services are single-instance only |
| Mounting at a disallowed path | Use a subdirectory (e.g. `/opt/render/project/src/uploads` not `/opt/render/project/src`) |
| Reading disk during build or pre-deploy | These run on separate compute — move logic to the start command |
| Restoring disk snapshot for a database | Use database-native backups instead |
| Starting with a large disk size | Start small — you can increase but never decrease |

## References

| Document | Contents |
|----------|----------|
| `references/sizing-and-snapshots.md` | Sizing guidance, snapshot lifecycle, restore procedures, cost patterns |

## Related Skills

- **render-web-services** — Deploy lifecycle, health checks (disk disables zero-downtime)
- **render-private-services** — Internal services with disks (Elasticsearch, MySQL)
- **render-blueprints** — `disk` field reference in `render.yaml`
- **render-postgres** — Managed database alternative (no disk management needed)

Referenced files: 1

View saved version →

---
name: render-docker
description: >-
  Builds and deploys Docker containers on Render—Dockerfiles, multi-stage
  builds, Blueprint Docker fields, private registries, layer caching, and
  platform constraints. Use when the user mentions Docker,
  Dockerfile, container images, multi-stage builds, container registry,
  GHCR, ECR, BuildKit, dockerContext, runtime docker or image, or
  optimizing Docker builds on Render.
license: MIT
compatibility: >-
  Any Render compute service (web, private, worker, cron) with runtime: docker
  or runtime: image.
metadata:
  author: Render
  version: "1.0.0"
  category: deployment
---

# Render Docker Deployments

Render uses **BuildKit** for Docker builds. All compute service types that support custom runtimes can use **`runtime: docker`** (build from a Dockerfile in the repo) or **`runtime: image`** (pull a prebuilt image; no Dockerfile build on Render). Deeper patterns and copy-paste templates live under `references/`.

## When to Use

- Authoring or debugging a **Dockerfile** for a Render service
- Choosing **`runtime: docker`** vs **`runtime: image`** in a Blueprint
- Wiring **private base images** or **prebuilt images** with registry credentials
- **Multi-stage builds**, **build args**, **secrets**, and **layer caching**
- **Performance** and **security** hardening of container images on Render

For full Blueprint authoring, see **render-blueprints**. For end-to-end deploy flows, see **render-deploy**.

## Render Docker Builds

- **BuildKit** is used for Docker builds on Render.
- **`runtime: docker`**: Render builds an image from your repo using `dockerfilePath`, `dockerContext`, and optional `dockerCommand` (overrides image `CMD`).
- **`runtime: image`**: Render pulls **`image.url`**; no repo-based image build. Pair with **`registryCredential`** when the registry is private.

## Blueprint Configuration

| Field | Role |
|-------|------|
| `dockerfilePath` | Path to the Dockerfile (default `./Dockerfile`) |
| `dockerContext` | Build context directory (what is sent to the daemon) |
| `dockerCommand` | Overrides the container `CMD` after the image is built |
| `image.url` | Image reference for `runtime: image` (registry/repo:tag or digest) |
| `registryCredential` | Auth for private pulls; often `fromRegistryCreds` → Dashboard-stored credential |

Example sketch (values illustrative):

```yaml
services:
  - type: web
    name: api
    runtime: docker
    region: oregon
    plan: starter
    dockerfilePath: ./Dockerfile
    dockerContext: .
    dockerCommand: node server.js
    envVars:
      - key: PORT
        value: 10000
```

For `runtime: image`, set `image.url` and, if needed, `registryCredential` per **Registry Configuration** below.

## Multi-Stage Builds

**Recommended for production.** Use a **builder** stage for compilation and dependency installation, and a minimal **runner** stage that only copies artifacts and runtime files. Benefits:

- Smaller images and faster pulls
- Fewer tools and secrets in the final image (smaller attack surface)
- Clear separation between build-time and run-time dependencies

See `references/dockerfile-patterns.md` for language-specific templates.

## Build Args vs Secrets

**Critical:** **Never pass secrets via `ARG`.** Build arguments are stored in image **layers** and can be recovered from the image history or intermediate layers.

- Prefer **runtime environment variables** (Render **env vars** / secret files) for application secrets.
- For **build-time** secrets (e.g. private package feeds), use **Docker BuildKit secret mounts** (`RUN --mount=type=secret,...`) rather than `ARG`.

Treat anything sensitive as **runtime** or **BuildKit secret mount**, not as a build arg.

## Registry Configuration

Private **base images** (for `runtime: docker`) or **prebuilt images** (`runtime: image`) need authentication:

- Store credentials in the Render Dashboard under **Registry Credentials**.
- In Blueprint, reference them with **`registryCredential.fromRegistryCreds.name`** (match the Dashboard name).

Supports common registries (Docker Hub, GHCR, ECR, Google Artifact Registry, and others). Step-by-step per provider: `references/registry-setup.md`.

**Prebuilt image services** do **not** auto-deploy when the tag moves in the registry; trigger a **manual redeploy** or use a **deploy hook** when you publish a new image.

## Layer Caching

- Render **caches Docker layers** between builds; **order Dockerfile instructions** so that frequently unchanged layers stay early (see `references/optimization-guide.md`).
- **Tags and caching:** mutable tags like **`latest`** can resolve to **stale cached** images. Prefer **immutable** references: **digest** (`repo/image@sha256:...`) or **version pins** (`v1.2.3`).

## Platform Specifics

- Render builds **linux/amd64**. Avoid assumptions about other architectures in production images.
- **Port binding** matches native services: bind HTTP to **`0.0.0.0:$PORT`** (Render sets `PORT`).
- **Health checks** behave like non-Docker web services (`healthCheckPath`, etc.).
- **Secret files** from Render appear under **`/etc/secrets/`** — do not rely on repo-root secret paths inside the container unless you copy or mount them explicitly in the image.

## `.dockerignore` and Start Commands

- Always maintain a **`.dockerignore`** that excludes **`node_modules`**, **`.git`**, **`.env`**, build artifacts, logs, and OS junk. This shrinks context upload time and avoids leaking local files into layers. Lists and rationale: `references/optimization-guide.md`.
- **Custom start command:** if you need multiple shell steps, use a single shell form, e.g. **`/bin/sh -c 'set -e; ./migrate && exec node server.js'`** (prefer **`exec`** so your app receives signals for graceful shutdown).

## References

| Document | Contents |
|----------|----------|
| `references/dockerfile-patterns.md` | Multi-stage templates (Node, Python, Go, Ruby, Rust, static sites) |
| `references/registry-setup.md` | Docker Hub, GHCR, ECR, Artifact Registry + Blueprint wiring |
| `references/optimization-guide.md` | Layer order, `.dockerignore`, BuildKit cache mounts, debugging |

## Related Skills

- **render-deploy** — Deploy flows, Blueprint vs Dashboard, operational steps
- **render-blueprints** — Full `render.yaml` schema, wiring, and validation
- **render-web-services** — Web service behavior, health checks, and HTTP edge cases

Referenced files: 3

View saved version →

---
name: render-domains
description: >-
  Configures custom domains and TLS certificates on Render—DNS setup, CNAME
  records, apex domains, wildcard domains, and certificate troubleshooting.
  Use when the user needs to add a custom domain, configure DNS, set up
  HTTPS/TLS, troubleshoot certificate issuance, disable the onrender.com
  subdomain, or add a wildcard domain.
  Trigger terms: custom domain, DNS, CNAME, TLS, SSL, HTTPS, certificate,
  apex domain, wildcard domain, onrender.com, domain verification.
license: MIT
compatibility: Render web services and static sites
metadata:
  author: Render
  version: "1.0.0"
  category: networking
---

# Render Custom Domains

Render automatically provisions and renews TLS certificates (via Let's Encrypt and Google Trust Services) for all custom domains. All HTTP traffic is redirected to HTTPS. Custom domains work on **web services** and **static sites** only.

## When to Use

- Adding a **custom domain** to a web service or static site
- Configuring **DNS records** (CNAME, A, or ALIAS) with a provider
- Setting up a **wildcard domain** (`*.example.com`)
- Troubleshooting **certificate issuance** or **domain verification** failures
- Choosing between **apex** (`example.com`) and **www** (`www.example.com`)
- **Disabling the `onrender.com` subdomain** after adding a custom domain

## Domain Limits

| Workspace tier | Custom domain limit |
|---------------|---------------------|
| Hobby | 2 custom domains (across all services) |
| Professional+ | Unlimited |

## Setup Steps

### 1. Add domain in Dashboard

1. Go to your service's **Settings > Custom Domains**
2. Click **+ Add Custom Domain**
3. Enter your domain (e.g. `app.example.com`)
4. Click **Save**

Adding a `www` subdomain automatically adds the root domain (and vice versa) with a redirect between them.

### 2. Configure DNS

Add a DNS record with your provider pointing to your Render service:

| Domain type | Record type | Name | Value |
|-------------|-------------|------|-------|
| **Subdomain** (`app.example.com`) | CNAME | `app` | `<service>.onrender.com` |
| **Apex** (`example.com`) on Cloudflare | CNAME (flattened) | `@` | `<service>.onrender.com` |
| **Apex** on other providers | A | `@` | Use Render-provided IP (see Dashboard) |

**Important:** Remove any `AAAA` (IPv6) records for your domain. Render uses IPv4, and stale `AAAA` records cause unexpected behavior.

Provider-specific guides:
- [Cloudflare](https://render.com/docs/configure-cloudflare-dns)
- [Namecheap](https://render.com/docs/configure-namecheap-dns)
- [Other providers](https://render.com/docs/configure-other-dns)

### 3. Verify domain

Click **Verify** in the Dashboard. If verification fails, DNS may not have propagated yet—wait a few minutes and retry.

Speed up verification by flushing DNS caches:
- [Google Public DNS](https://developers.google.com/speed/public-dns/cache)
- [Cloudflare DNS](https://1.1.1.1/purge-cache/)
- [OpenDNS](https://cachecheck.opendns.com/)

After verification, Render issues a TLS certificate automatically.

## Wildcard Domains

Wildcard domains (`*.example.com`) route all matching subdomains to one service.

Requires **three CNAME records**:

| Name | Value | Purpose |
|------|-------|---------|
| `*` | `<service>.onrender.com` | Routes traffic |
| `_acme-challenge` | `<service-id>.verify.renderdns.com` | Let's Encrypt validation |
| `_cf-custom-hostname` | `<service-id>.hostname.renderdns.com` | Cloudflare DDoS validation |

**Cloudflare users:** If you add `*.example.com` without adding the root domain to Render, disable proxying (gray cloud) for the root domain to avoid routing conflicts.

## CAA Records

If your domain has `CAA` records, add entries for Render's certificate authorities:

```
example.com IN CAA 0 issue "letsencrypt.org"
example.com IN CAA 0 issuewild "letsencrypt.org"
example.com IN CAA 0 issue "pki.goog; cansignhttpexchanges=yes"
example.com IN CAA 0 issuewild "pki.goog; cansignhttpexchanges=yes"
```

Without these, TLS certificate issuance fails silently.

## Disabling the `onrender.com` Subdomain

After adding at least one custom domain, you can disable the default `onrender.com` subdomain:

1. Settings > Custom Domains > **Render Subdomain** > toggle to **Disabled**
2. All requests to the `onrender.com` URL receive a 404
3. Can be re-enabled at any time

## Blueprint Configuration

Custom domains are specified in the `domains` field:

```yaml
services:
  - type: web
    name: api
    runtime: node
    plan: starter
    domains:
      - app.example.com
      - www.example.com
```

Blueprint `domains` only **declare** the domain association. You still need to configure DNS with your provider manually.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| AAAA records present | Remove all IPv6 AAAA records for the domain |
| CAA records blocking issuance | Add `letsencrypt.org` and `pki.goog` entries |
| Verifying too quickly | Wait 2-5 minutes for DNS propagation, then flush caches |
| Cloudflare proxy + wildcard without root domain | Disable proxying (gray cloud) for the root domain |
| Trying to add domain to a private service | Custom domains only work on web services and static sites |
| 502 after verification | Routing rules are updating — wait a few minutes |

## References

| Document | Contents |
|----------|----------|
| `references/dns-configuration.md` | Provider-specific DNS setup, apex domain options, TTL recommendations |

## Related Skills

- **render-web-services** — Web service configuration, TLS, port binding
- **render-static-sites** — Static site domains, CDN, headers
- **render-blueprints** — `domains` field in `render.yaml`

Referenced files: 1

View saved version →

---
name: render-env-vars
description: >-
  Configures environment variables, secrets, and env groups on Render. Use when
  the user needs to set env vars, wire secrets between services, create env
  groups, use generateValue, set sync: false, or troubleshoot missing or
  incorrect environment variable values in Blueprints or the Dashboard.
license: MIT
compatibility: Render Dashboard, CLI, or MCP tools
metadata:
  author: Render
  version: "1.0.0"
  category: configuration
---

# Environment Variables on Render

Render exposes configuration to services as **environment variables**. Values are always **strings** at the platform layer—applications must parse numbers, booleans, and structured data explicitly.

There are **three** primary ways to set variables:

1. **Render Dashboard** — per-service UI, bulk import from `.env`, save/redeploy options
2. **Blueprint** — `envVars` (and related keys) in `render.yaml`
3. **MCP / API** — e.g. `update_environment_variables` on a service

Deep wiring patterns, full platform variable tables, and language-specific notes live under `references/`.

## When to Use This Skill

Use this skill when users want to:

- Add, change, or remove environment variables or secrets
- Understand Dashboard vs Blueprint vs API/MCP flows
- Use **environment groups** for shared configuration
- Wire `fromDatabase`, `fromService`, `fromGroup`, `sync: false`, or `generateValue` in Blueprints
- Debug missing vars, secret files, precedence, or platform-injected names

For full Blueprint authoring, pair with **render-blueprints**. For first-time deploys, **render-deploy**. For web service behavior and ports, **render-web-services**.

## Setting Variables

### Dashboard

- Add variables **individually** (name + value) or **in bulk** by pasting/uploading a `.env`-style file.
- **Save options** typically include:
  - **Save and rebuild & deploy** — picks up build-time changes
  - **Deploy only** — runtime change without a full rebuild (when applicable)
  - **Save only** — persist without triggering a deploy

Use Dashboard edits when iterating quickly or when the repo should not carry certain values.

### Blueprint (`render.yaml`)

Declare `envVars` on each service. Values can be literals, generated secrets, sync-disabled prompts, or references to databases, other services, or env groups. See **Blueprint Wiring** below and `references/wiring-reference.md` for exhaustive patterns and YAML.

### MCP / API

Automation tools can set variables on existing services (e.g. `update_environment_variables`). Useful for CI, rotation, or keeping Dashboard state in sync with external secret stores—without committing secrets to Git.

## Secret Management

- **`sync: false`** — Render prompts in the Dashboard for the value **only on initial Blueprint setup** when the resource is first created. On **Blueprint updates**, `sync: false` is **ignored** (values are not re-prompted from the file alone). These vars are **excluded from preview environments** and are **invalid inside environment groups**.
- **`generateValue: true`** — Render generates a **base64-encoded 256-bit** random value at provision time. Use for passwords, signing keys, or tokens that do not need human-chosen values.
- **Never commit real secrets** in `render.yaml` as plain `value:` entries. Prefer Dashboard, secret manager integration, `generateValue`, or `sync: false` with Dashboard entry.

### Secret files

- Store sensitive file content as **secret files** (not inline env strings). They appear as **plaintext files** under **`/etc/secrets/<filename>`**.
- **Combined limit**: **1 MB** total secret file payload per service or per linked env group (as applicable to your setup).
- **Docker**: secret files are available under **`/etc/secrets/`** on the running instance.

## Environment Groups

**Environment groups** are named collections of variables linked to **multiple services**.

- **Precedence**: **Service-level** variables **override** variables from linked groups with the same name.
- **Multiple groups** on one service: the group that was **most recently created** wins for overlapping keys. This ordering is **not documented as stable**—avoid relying on it; use distinct names or consolidate groups.
- Groups can be **scoped to a project environment** so staging and production differ without duplicating every service definition.

## Blueprint Wiring (Summary)

Full syntax, examples, and edge cases: `references/wiring-reference.md`. Authoritative Blueprint docs: **render-blueprints** skill.

| Mechanism | Role |
|-----------|------|
| `value` | Hardcoded string (non-secret config only) |
| `generateValue: true` | Platform-generated secret |
| `sync: false` | Dashboard prompt on **initial** create only |
| `fromDatabase` | Inject DB fields (`connectionString`, `host`, `port`, `user`, `password`, `database`) |
| `fromService` | Key Value: `type: keyvalue` + properties; private/web: `host`, `hostport`, or `envVarKey` |
| `fromGroup` | Link all vars from a named group |

## Platform-Injected Variables

Render sets **read-only** variables your app can read at runtime (and some at build). A concise list:

| Variable | Typical meaning |
|----------|-----------------|
| `RENDER` | `"true"` when running on Render |
| `RENDER_SERVICE_TYPE` | Service kind (e.g. web, worker) |
| `RENDER_SERVICE_ID` | Service identifier |
| `RENDER_SERVICE_NAME` | Human-readable service name |
| `RENDER_INSTANCE_ID` | Current instance |
| `RENDER_EXTERNAL_URL` | Public URL (when applicable) |
| `RENDER_EXTERNAL_HOSTNAME` | Public hostname |
| `RENDER_DISCOVERY_SERVICE` | Service discovery hostname (private network) |
| `RENDER_GIT_COMMIT` | Deployed commit SHA |
| `RENDER_GIT_BRANCH` | Branch for this deploy |
| `PORT` | HTTP port to bind (**default `10000`**) |
| `IS_PULL_REQUEST` | Preview deploy indicator |
| `RENDER_CPU_COUNT` | vCPU count for the instance |
| `RENDER_WEB_CONCURRENCY` | Suggested worker/process count hint |

Build vs runtime availability, language version env vars, and **WEB_CONCURRENCY** defaults: `references/platform-variables.md`.

## Runtime-Specific Defaults

Render and buildpacks may set defaults (verify in your service’s **Environment** tab):

| Runtime | Notable defaults |
|---------|------------------|
| **Node.js** | `NODE_ENV=production` |
| **Python** | `PYTHON_VERSION` (pinned by build); Gunicorn-oriented images often set `GUNICORN_CMD_ARGS` to bind **`0.0.0.0:10000`** |
| **Ruby** | `RAILS_ENV=production`, `RAILS_LOG_TO_STDOUT=true` |
| **Go** | `GO111MODULE=on` (legacy modules flag; still seen on older stacks) |
| **Rust** | `ROCKET_PORT=10000` (Rocket convention) |

Always bind HTTP servers to **`0.0.0.0`** and **`PORT`** (or the stack’s documented port env) unless using a static site or custom Docker entrypoint.

## Common Issues

1. **Everything is a string** — `DEBUG=false` is truthy in many parsers; use explicit comparison or typed config loaders.
2. **`WEB_CONCURRENCY`** — Default behavior changed for services **created after December 8, 2025**. Compare with older services when debugging worker counts; see `references/platform-variables.md`.
3. **Undocumented `RENDER_*` variables** — Names and semantics may change; do not depend on undocumented injection for critical logic.
4. **Blueprint vs Dashboard drift** — Editing only `render.yaml` does not retroactively apply `sync: false` prompts on update; merge strategy for env keys is easy to misunderstand—test in a scratch service.
5. **Secret file paths** — Code must read **`/etc/secrets/<filename>`**; wrong paths or missing mounts usually show as file-not-found at runtime.

## References

- `references/wiring-reference.md` — Complete Blueprint `envVar` wiring, YAML examples, precedence, edge cases
- `references/platform-variables.md` — Injected variables (build vs runtime), language versions, concurrency, reading vars from code

## Related Skills

- **render-blueprints** — Full Blueprint authoring, validation, multi-service layouts
- **render-deploy** — First deploy, repo requirements, MCP vs YAML
- **render-web-services** — Ports, health checks, scaling behavior tied to env-driven servers

Referenced files: 2

View saved version →

---
name: render-keyvalue
description: >-
  Provisions and configures Render Key Value (Redis-compatible Valkey 8)
  instances for caching, session storage, and job queues. Use when the user
  needs Redis, Key Value, Valkey, a cache, session store, job queue backend,
  or needs to configure maxmemory policy, ipAllowList, connection strings,
  or internal vs external access.
  Trigger terms: Key Value, Redis, Valkey, cache, session store, REDIS_URL,
  maxmemory, ipAllowList, allkeys-lru, noeviction.
license: MIT
compatibility: Render Key Value instances (free and paid plans)
metadata:
  author: Render
  version: "1.0.0"
  category: data
---

# Render Key Value

Render Key Value provides low-latency, Redis-compatible in-memory storage running **Valkey 8**. Use it as a shared cache, session store, or job queue backend. Compatible with virtually all Redis client libraries.

## When to Use

- Adding a **cache** or **session store** to a web app
- Wiring a **job queue** backend for Celery, Sidekiq, BullMQ, Asynq, or Oban
- Choosing the right **maxmemory policy** (cache vs queue)
- Configuring **ipAllowList** in Blueprints (required field)
- Connecting via **internal vs external URLs**
- Troubleshooting **auth failures** or **connection refused** errors

For background worker setup and queue framework patterns, see **render-background-workers**. For Blueprint authoring, see **render-blueprints**.

## Key Concepts

### Valkey 8 (not Redis)

New instances run **Valkey 8**, an open-source Redis fork. It is a drop-in replacement for Redis—existing Redis client libraries work without changes. Legacy instances (created before Feb 2025) run Redis 6.

### Connection URLs

Every instance has two URLs:

| URL type | When to use | Auth required |
|----------|-------------|---------------|
| **Internal** (`redis://red-xxx:6379`) | From Render services in the same region | No (by default) |
| **External** (`rediss://red-xxx:6379`) | From outside Render (local dev, CI) | Always |

**Always prefer the internal URL** for production services—lower latency, no TLS overhead, communicates over the private network.

External connections are **disabled by default**. Enable them by adding IP ranges to the access control list in the Dashboard.

### Internal authentication

By default, internal connections are unauthenticated. You can **require auth for internal connections** in the Dashboard for compliance or extra security. This changes the internal URL to include credentials:

```
redis://default:PASSWORD@red-xxx:6379
```

**Warning:** Enabling internal auth breaks existing unauthenticated connections. Migrate clients to the authenticated URL first.

## Maxmemory Policy

**Critical decision.** Choose based on your use case:

| Use case | Policy | Why |
|----------|--------|-----|
| **Cache** (can lose data) | `allkeys-lru` | Evicts least-recently-used keys to free space |
| **Job queue** (cannot lose data) | `noeviction` | Returns error on writes when full; never drops keys |
| **Session store** | `allkeys-lru` or `volatile-lru` | Sessions can be regenerated; LRU is safe |

All available policies:

| Policy | Behavior | Memory fills up? |
|--------|----------|-----------------|
| `allkeys-lru` | Evict any key by LRU | No |
| `noeviction` | Error on writes when full | Yes |
| `volatile-lru` | Evict keys with TTL by LRU | Yes |
| `volatile-lfu` | Evict keys with TTL by LFU | Yes |
| `allkeys-lfu` | Evict any key by LFU | No |
| `volatile-random` | Evict random keys with TTL | Yes |
| `allkeys-random` | Evict any random key | No |
| `volatile-ttl` | Evict keys nearest to expiry | Yes |

## Blueprint Configuration

```yaml
services:
  - type: keyvalue
    name: cache
    plan: starter
    region: oregon
    maxmemoryPolicy: allkeys-lru
    ipAllowList: []
```

### `ipAllowList` is required

Blueprints **must** include `ipAllowList` on Key Value services. Common patterns:

| Value | Meaning |
|-------|---------|
| `[]` | No external access (internal only—**recommended for most apps**) |
| `[{source: "0.0.0.0/0", description: "everywhere"}]` | Open external access (use sparingly) |
| `[{source: "203.0.113.0/24", description: "office"}]` | Specific IP ranges |

### Wiring to services

Use `fromService` with `type: keyvalue` and `property: connectionString`:

```yaml
envVars:
  - key: REDIS_URL
    fromService:
      name: cache
      type: keyvalue
      property: connectionString
```

Available `fromService` properties for Key Value:

| Property | Value |
|----------|-------|
| `connectionString` | Full internal URL (`redis://red-xxx:6379`) |
| `host` | Hostname only |
| `port` | Port only (typically `6379`) |

## Data Persistence

- **Paid instances:** Disk-backed, `appendfsync everysec`. You may lose up to 1 second of writes on interruption.
- **Free instances:** No disk persistence. Data is lost on restart or upgrade.
- **Upgrading from Free:** All data is lost during the upgrade because Free instances have no disk.

## Instance Types and Upgrades

- Instance type determines **RAM** and **connection limit**
- You can **upgrade** to a larger type (brief downtime, ~1-2 minutes)
- You **cannot downgrade** to a smaller type
- For instances larger than 10 GB RAM, contact Render support

## Connection Examples

See `references/connection-examples.md` for client code in Node.js (ioredis, node-redis), Python (redis-py), Ruby (redis-rb, Sidekiq), and Go.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Missing `ipAllowList` in Blueprint | Add `ipAllowList: []` for internal-only access |
| Using `allkeys-lru` for job queues | Switch to `noeviction`—LRU eviction drops queued jobs |
| Connecting with external URL from a Render service | Use the internal URL for lower latency and no auth requirement |
| Forgetting `type: keyvalue` in `fromService` | `type` is required; without it the wiring fails |
| Using deprecated `redis` type alias | Prefer `keyvalue` in new Blueprints (`redis` still works but is deprecated) |

## References

| Document | Contents |
|----------|----------|
| `references/connection-examples.md` | Client code for Node.js, Python, Ruby, Go |
| `references/troubleshooting.md` | Auth errors, connection refused, memory full, migration from Redis 6 |

## Related Skills

- **render-background-workers** — Queue consumer setup with Celery, Sidekiq, BullMQ
- **render-blueprints** — Full `render.yaml` schema, `fromService` patterns
- **render-networking** — Private network, internal URLs
- **render-env-vars** — Wiring `REDIS_URL` and other connection vars

Referenced files: 2

View saved version →

---
name: render-mcp
description: >-
  Connects and configures the Render MCP server for AI coding tools—setup per
  tool (Cursor, Claude Code, Codex), authentication, workspace selection, tool
  catalog, and troubleshooting. Use when MCP is not configured, list_services()
  fails, the user asks about Render MCP setup, or an action skill needs MCP
  but it's not connected yet.
  Trigger terms: MCP, Render MCP, list_services, MCP setup, MCP server,
  OAuth, API key, Bearer token, mcp.render.com, workspace selection.
license: MIT
compatibility: Render MCP server (hosted at mcp.render.com)
metadata:
  author: Render
  version: "1.0.0"
  category: operations
---

# Render MCP Server

The Render MCP server lets AI coding tools manage Render services, databases, deploys, logs, and metrics directly. This skill covers **setup**, **authentication**, **workspace selection**, the **tool catalog**, and **troubleshooting**.

Action skills (render-deploy, render-debug, render-monitor) use MCP tools for their workflows. If MCP is not connected, set it up using this skill first.

## When to Use

- `list_services()` fails or MCP tools are unavailable
- First-time Render MCP setup for any AI tool
- User asks how to connect their AI tool to Render
- Switching workspaces or troubleshooting auth errors
- Discovering which MCP tools exist and what they do

## Connection Details

| Property | Value |
|----------|-------|
| URL | `https://mcp.render.com/mcp` |
| Transport | HTTP (streamable) |
| Auth | OAuth when installed via the Render plugin (pre-registered client id); bearer token (API key) for manual setup |
| API key page | `https://dashboard.render.com/u/*/settings#api-keys` (manual setup) |
| Docs | `https://render.com/docs/mcp-server` |

## Setup by Tool

### Render plugin (recommended)

The Render plugin for Cursor, Codex, and Claude Code bundles this MCP server with a pre-registered OAuth client id, so no API key is needed. After installing or updating the plugin, reload the tool (restart Cursor or Claude Code, or start a new Codex thread) so it loads the plugin-provided MCP server, then complete the Render OAuth prompt the first time MCP tools are used. Verify with `list_services()`.

The manual, API-key setups below are for tools without the plugin or for custom MCP configurations.

### Cursor

1. Get an API key from the [Render Dashboard](https://dashboard.render.com/u/*/settings#api-keys)

2. Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "render": {
      "url": "https://mcp.render.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

3. Restart Cursor, then verify with `list_services()`

### Claude Code

1. Get an API key from the [Render Dashboard](https://dashboard.render.com/u/*/settings#api-keys)

2. Add the MCP server:

```bash
claude mcp add --transport http render https://mcp.render.com/mcp --header "Authorization: Bearer <YOUR_API_KEY>"
```

3. Restart Claude Code, then verify with `list_services()`

### Codex

1. Get an API key from the [Render Dashboard](https://dashboard.render.com/u/*/settings#api-keys)

2. Set the key in your shell:

```bash
export RENDER_API_KEY="<YOUR_API_KEY>"
```

3. Add the MCP server:

```bash
codex mcp add render --url https://mcp.render.com/mcp --bearer-token-env-var RENDER_API_KEY
```

4. Restart Codex, then verify with `list_services()`

### Other Tools

For tools not listed above, use the generic HTTP MCP configuration:

- **URL:** `https://mcp.render.com/mcp`
- **Auth header:** `Authorization: Bearer <YOUR_API_KEY>`
- **Transport:** HTTP (streamable HTTP, not SSE)

See [Render MCP docs](https://render.com/docs/mcp-server) for tool-specific instructions.

## Workspace Selection

After MCP is connected, set the active workspace:

```
Set my Render workspace to [WORKSPACE_NAME]
```

Or programmatically:

```
get_selected_workspace()   # Check current
list_workspaces()          # List available
```

All MCP operations run against the active workspace.

## Tool Catalog

### Service management

| Tool | Purpose |
|------|---------|
| `list_services()` | List all services and datastores |
| `get_service(serviceId)` | Get service details |
| `create_web_service(...)` | Create a web service from Git repo |
| `create_static_site(...)` | Create a static site from Git repo |
| `update_service(serviceId, ...)` | Update service configuration |
| `restart_service(serviceId)` | Restart a service |

### Deploys

| Tool | Purpose |
|------|---------|
| `list_deploys(serviceId, limit)` | List deploys for a service |
| `trigger_deploy(serviceId)` | Trigger a new deploy |

### Logs

| Tool | Purpose |
|------|---------|
| `list_logs(resource, level, type, text, statusCode, limit)` | Query logs with filters |

Key filters: `level` (error, warn, info), `type` (build, deploy), `text` (search string), `statusCode` (HTTP codes).

### Metrics

| Tool | Purpose |
|------|---------|
| `get_metrics(resourceId, metricTypes, ...)` | Get service or database metrics |

Metric types: `cpu_usage`, `memory_usage`, `cpu_limit`, `memory_limit`, `http_latency`, `http_request_count`, `active_connections`.

Optional: `httpLatencyQuantile` (0.5, 0.95, 0.99), `httpPath` (filter by endpoint).

### Databases

| Tool | Purpose |
|------|---------|
| `list_postgres_instances()` | List Postgres databases |
| `get_postgres(postgresId)` | Get database details |
| `query_render_postgres(postgresId, sql)` | Run SQL query |

### Key Value

| Tool | Purpose |
|------|---------|
| `list_key_value()` | List Key Value instances |
| `get_key_value(keyValueId)` | Get Key Value details |

### Environment Variables

| Tool | Purpose |
|------|---------|
| `update_environment_variables(serviceId, envVars)` | Set env vars on a service |

### Workspace

| Tool | Purpose |
|------|---------|
| `list_workspaces()` | List available workspaces |
| `get_selected_workspace()` | Get the active workspace |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Wrong URL (using SSE endpoint) | Use `https://mcp.render.com/mcp` (not `/sse`) |
| Plugin installed but MCP tools unavailable | Reload the tool (restart, or start a new thread) so it loads the plugin's MCP server |
| OAuth prompt does not appear | Reinstall or update the Render plugin, then reload the tool |
| Expired or invalid API key | Generate a new key from Dashboard > Account Settings > API Keys |
| Wrong workspace selected | Run `list_workspaces()` and switch to the correct one |
| Using MCP to create image-backed services | Not supported — use Dashboard or API for prebuilt Docker images |
| Missing `Bearer` prefix in auth header | Header must be `Authorization: Bearer <key>` |

## Troubleshooting

See `references/troubleshooting.md` for connection errors, auth failures, timeout issues, and tool-specific quirks.

## References

| Document | Contents |
|----------|----------|
| `references/troubleshooting.md` | Connection errors, auth failures, tool-specific issues, timeout handling |

## Related Skills

- **render-deploy** — Deploy flows using MCP tools
- **render-debug** — Debug failures using MCP logs and metrics
- **render-monitor** — Monitor health using MCP metrics
- **render-cli** — CLI alternative when MCP is unavailable

Referenced files: 1

View saved version →

---
name: render-migrate-from-heroku
description: "Migrate from Heroku to Render by reading local project files and generating equivalent Render services. Triggers: any mention of migrating from Heroku, moving off Heroku, Heroku to Render migration, or switching from Heroku. Reads Procfile, dependency files, and app config from the local repo. Optionally uses Heroku MCP to enrich with live config vars, add-on details, and dyno sizes. Uses Render MCP or Blueprint YAML to create services."
license: MIT
compatibility: Render MCP server recommended for direct creation and automated verification; not required for the Blueprint path. Heroku MCP server is optional (enhances config var and add-on discovery).
metadata:
  author: Render
  version: "1.5.0"
  category: migration
---

# Heroku to Render Migration

Migrate from Heroku to Render by reading local project files first, then optionally enriching with live Heroku data via MCP.

## Prerequisites Check

Before starting, verify what's available:

1. **Local project files** (required) — confirm the current directory contains a Heroku app (look for `Procfile`, `app.json`, `package.json`, `requirements.txt`, `Gemfile`, `go.mod`, or similar)
2. **Render MCP** (recommended) — check if `list_services` tool is available. Required for MCP Direct Creation (Step 3B) and automated verification (Step 6). Not required for the Blueprint path — the Render CLI and Dashboard handle generation, validation, and deployment.
3. **Heroku MCP** (optional) — check if `list_apps` tool is available

If Render MCP is missing and the user needs it, guide them through setup using the [MCP setup guide](references/mcp-setup.md). If Heroku MCP is missing, note that config var values and add-on plan details will need to be provided manually.

## Migration Workflow

Execute steps in order. Present findings to the user and get confirmation before creating any resources.

### Step 1: Inventory Heroku App

Gather app details from local files first, then supplement with Heroku MCP if available.

#### 1a. Read local project files (always)

Read these files from the repo to determine runtime, commands, and dependencies:

| File                                              | What it tells you                                                      |
| ------------------------------------------------- | ---------------------------------------------------------------------- |
| `Procfile`                                        | Process types and start commands (`web`, `worker`, `clock`, `release`) |
| `package.json`                                    | Node.js runtime, build scripts, framework deps (Next.js, React, etc.)  |
| `requirements.txt` / `Pipfile` / `pyproject.toml` | Python runtime, dependencies (Django, Flask, etc.)                     |
| `Gemfile`                                         | Ruby runtime, dependencies (Rails, Sidekiq, etc.)                      |
| `go.mod`                                          | Go runtime                                                             |
| `Cargo.toml`                                      | Rust runtime                                                           |
| `app.json`                                        | Declared add-ons, env var descriptions, buildpacks                     |
| `runtime.txt`                                     | Pinned runtime version                                                 |
| `static.json`                                     | Static site indicator                                                  |
| `yarn.lock` / `pnpm-lock.yaml`                    | Package manager (affects build command)                                |

From these files, determine:

- **Runtime** — from dependency files (see the [buildpack mapping](references/buildpack-mapping.md))
- **Runtime version** — from `runtime.txt`, `.node-version`, or `engines` in `package.json`. If pinned, carry it over as an env var (e.g., `PYTHON_VERSION`, `NODE_VERSION`). If not pinned, do not specify a version — never assume or state what Render's default version is.
- **Build command** — from package manager and framework (see the [buildpack mapping](references/buildpack-mapping.md))
- **Start commands** — from `Procfile` entries
- **Process types** — from `Procfile` (web, worker, clock, release)
- **Add-ons needed** — from `app.json` `addons` field, or infer from dependency files (e.g., `pg` in `package.json` suggests Postgres, `redis` suggests Key Value)
- **Static site?** — from `static.json`, SPA framework deps, or static buildpack in `app.json`

#### 1b. Enrich with Heroku MCP (if available)

If the Heroku MCP server is connected, call these tools to fill in details that aren't in the repo. The **dyno size** and **add-on plan slug** are critical — they determine which Render plans to use.

1. `list_apps` — let user select which app to migrate (confirms app name)
2. `get_app_info` — capture: region, stack, buildpacks, **config var names**
3. `list_addons` — capture the **exact add-on plan slug** (e.g., `heroku-postgresql:essential-2`, `heroku-redis:premium-0`). The part after the colon maps to a specific Render plan in the [service mapping](references/service-mapping.md).
4. `ps_list` — capture the **exact dyno size** for each process type (e.g., `Standard-2X`, `Performance-M`). Each dyno size maps to a specific Render plan in the [service mapping](references/service-mapping.md).
5. `pg_info` (if Postgres exists) — capture **Data Size** (actual usage) and the plan's disk allocation. The plan's disk size determines the `diskSizeGB` value in the Blueprint (see the [service mapping](references/service-mapping.md)).

If Heroku MCP is **not** available, ask the user to provide:

- Dyno sizes (or run `heroku ps:type -a <app>` and paste output)
- Add-on plans (or run `heroku addons -a <app>` and paste output)
- Database info (or run `heroku pg:info -a <app>` and paste output — captures plan name, data size, and disk allocation)
- App region (`us` or `eu`)
- Config var names (or run `heroku config -a <app> --shell` and paste output)

If the user cannot provide dyno sizes or add-on plans, use the fallback defaults from the [service mapping](references/service-mapping.md): `starter` for compute, `basic-1gb` for Postgres, `starter` for Key Value.

#### Present summary

```
App: [name] | Region: [region] | Runtime: [node/python/ruby/etc]
Source: [local files | local files + Heroku MCP]
Build command: [inferred from buildpack/deps]
Processes:
  web: [command from Procfile] → Render web service ([mapped-plan])
  worker: [command] → Render background worker ([mapped-plan], Blueprint only)
  clock: [command] → Render cron job ([mapped-plan])
  release: [command] → Append to build command
Add-ons:
  Heroku Postgres ([plan-slug], [disk-size]) → Render Postgres ([mapped-plan], diskSizeGB: [size])
  Heroku Redis ([plan-slug]) → Render Key Value ([mapped-plan])
Config vars: 14 total (list names, not values)
```

### Step 2: Pre-Flight Check

Before creating anything, run through the [pre-flight checklist](references/preflight-checklist.md) to validate the migration plan. Key checks:

- Runtime supported (or needs Dockerfile)
- Worker dynos, release phase, static site detection
- Third-party add-ons without Render equivalents
- Git remote exists and is HTTPS format
- Database size (large DBs need assisted migration)

Look up each Heroku dyno size and add-on plan in the [service mapping](references/service-mapping.md) to determine correct Render plans and cost estimates. Present the migration plan table from the [pre-flight checklist](references/preflight-checklist.md) and wait for user confirmation before creating any resources.

### Determine Creation Method

After the user approves the pre-flight plan, apply this decision rule. **Default to Blueprint** — only use MCP Direct Creation when every condition below is met.

**Use Blueprint** (the default) when ANY are true:

- Multiple process types (web + worker, web + cron, etc.)
- Databases or Key Value stores needed
- Background workers in the Procfile
- User prefers Infrastructure-as-Code configuration

**Fall back to MCP Direct Creation** ONLY when ALL are true:

- Single web or static site service (one process type)
- No background workers or cron jobs
- No databases or Key Value stores

If unsure, use Blueprint. Most Heroku apps have at least a database, so Blueprint applies to the vast majority of migrations.

### Step 3A: Generate Blueprint (Multi-Service)

This step has three mandatory sub-steps. Complete all three in order.

#### 3A-i. Write render.yaml

Generate a `render.yaml` file and write it to the repo root. See the [Blueprint example](references/blueprint-example.md) for a complete example, the [Blueprint docs](https://render.com/docs/blueprint-spec#projects-and-environments) for usage guidance, and the [Blueprint YAML JSON schema](https://render.com/schema/render.yaml.json) for the full field reference.

**IMPORTANT: Always use the `projects`/`environments` pattern.** The YAML must start with a `projects:` key — never use flat top-level `services:` or `databases:` keys. This groups all migrated resources into a single Render project.

**Set the `plan:` field for each service and database using the mapped Render plan from the [service mapping](references/service-mapping.md).** Look up the Heroku dyno size (from `ps_list`) and add-on plan slug (from `list_addons`) to find the correct Render plan. If the Heroku plan is unknown, use the fallback defaults: `starter` for compute, `basic-1gb` for Postgres, `starter` for Key Value.

Generate the YAML following the full template, rules, and patterns in the [Blueprint example](references/blueprint-example.md). Critical rules:

- Always use the `projects:`/`environments:` pattern — never flat top-level `services:`
- Set every `plan:` field using the [service mapping](references/service-mapping.md)
- Set `diskSizeGB` on databases from the Heroku disk allocation
- Use `fromDatabase` for `DATABASE_URL` and `fromService` for `REDIS_URL` — never hardcode connection strings
- Mark secrets with `sync: false`

#### 3A-ii. Validate the Blueprint

This step is mandatory. First, check if the Render CLI is installed:

```bash
render --version
```

If not installed, offer to install it:

- macOS: `brew install render`
- Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh`

Once the CLI is available, run the validation command and show the output to the user:

```bash
render blueprints validate render.yaml
```

If validation fails, fix the errors in the YAML and re-validate. Repeat until validation passes. **Do not proceed to the next step until the Blueprint validates successfully.**

#### 3A-iii. Provide the deploy URL

After validation passes:

1. Instruct user to commit and push: `git add render.yaml && git commit -m "Add Render migration Blueprint" && git push`
2. Get the repo URL by running `git remote get-url origin`. If the URL is SSH format (e.g., `git@github.com:user/repo.git`), convert it to HTTPS (`https://github.com/user/repo`). Then construct the deeplink: `https://dashboard.render.com/blueprint/new?repo=<HTTPS_REPO_URL>`
3. Present the **actual working deeplink** to the user — never show a placeholder URL. Guide user to open it, fill in `sync: false` secrets, and click **Apply**

**Do not skip the deploy URL.** The user needs this link to apply the Blueprint on Render.

### Step 3B: MCP Direct Creation (Single-Service)

Before creating resources via MCP, verify the active workspace:

```
get_selected_workspace()
```

If the workspace is wrong, list available workspaces with `list_workspaces()` and ask the user to select the correct one. Resources will be created in whichever workspace is active.

For single-service migrations without databases, create via MCP tools:

1. **Web service** — `create_web_service` with:
   - `runtime`: from the [buildpack mapping](references/buildpack-mapping.md)
   - `buildCommand`: from the [buildpack mapping](references/buildpack-mapping.md)
   - `startCommand`: from Procfile `web:` entry
   - `repo`: user-provided GitHub/GitLab URL
   - `region`: mapped from Heroku region
   - `plan`: mapped from Heroku dyno size using the [service mapping](references/service-mapping.md) (fallback: `starter`)
2. **Static site** — `create_static_site` if detected (instead of web service)

Present the creation result (service URL, ID) when complete.

### Step 4: Migrate Environment Variables

#### Gather config vars

Use the first available source:

1. **Heroku MCP** (preferred) — config vars from `get_app_info` results (Step 1b)
2. **User-provided** — ask the user to paste output of `heroku config -a <app> --shell`
3. **`app.json`** — var names and descriptions (no values, but useful for `sync: false` entries)

#### Filter and categorize

Remove auto-generated and Heroku-specific vars (see the full filter list in the [service mapping](references/service-mapping.md)):

- `DATABASE_URL`, `REDIS_URL`, `REDIS_TLS_URL` (Render generates these)
- `HEROKU_*` vars (e.g., `HEROKU_APP_NAME`, `HEROKU_SLUG_COMMIT`)
- Add-on connection strings (`PAPERTRAIL_*`, `SENDGRID_*`, etc.)

Present filtered list to user — **do not write without confirmation**.

#### Apply vars

**Blueprint path (Step 3A):** Env vars are already embedded in the `render.yaml` on each service (non-secret values inline, secrets marked `sync: false` for the user to fill in during Blueprint apply). No separate MCP call is needed — skip to Step 5.

**MCP path (Step 3B):** Call Render `update_environment_variables` with confirmed vars (supports bulk set, merges by default).

### Step 5: Data Migration

Follow the [data migration guide](references/data-migration.md) to migrate Postgres and Redis data. The guide covers sub-steps 5a through 5e in detail. Summary of the flow:

1. **Pre-migration checks** — confirm Render resources are provisioned via `list_postgres_instances()` and `list_key_value()`, check source DB size, verify Render CLI (`render --version`), `pg_dump`, and `pg_restore` are installed
2. **Gather connection strings** — Heroku Postgres via `pg_credentials` (MCP) or user CLI paste. For Key Value, construct a Dashboard deeplink from the ID.
3. **Postgres migration** — two approaches based on size: **under 2 GB** uses `render psql` (no Render connection string needed); **2-50 GB** uses `pg_dump -Fc` + `pg_restore` with external connection string from Dashboard (faster, compressed, parallel restore).
4. **Key Value / Redis** — usually skip (ephemeral cache). If persistent data, use `redis-cli` dump/restore with Dashboard-provided Render URL.
5. **Data validation** — verify schema and row counts via `query_render_postgres`, compare against Heroku source if MCP is available.

### Step 6: Verify Migration

After user confirms database migration is complete, run through each check in order. Stop at the first failure, fix it, and redeploy before continuing.

#### 1. Confirm deploy status

```
list_deploys(serviceId: "<service-id>", limit: 1)
```

Expect `status: "live"`. If status is `failed`, inspect build and runtime logs immediately.

#### 2. Verify service health

Hit the health endpoint (or `/`) and confirm a 200 response. If there is no health endpoint, verify the app binds to `0.0.0.0:$PORT` (not `localhost`).

#### 3. Scan error logs

```
list_logs(resource: ["<service-id>"], level: ["error"], limit: 50)
```

Look for clear failure signatures: missing env vars, connection refused, module not found, port binding errors.

#### 4. Verify env vars and port binding

Confirm all required env vars are set — especially secrets marked `sync: false` during Blueprint apply. Ensure the app binds to `0.0.0.0:$PORT`.

#### 5. Check resource metrics

```
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_request_count", "cpu_usage", "memory_usage"]
)
```

Verify CPU and memory are within expected ranges for the selected plan.

#### 6. Confirm database connectivity

```
query_render_postgres(postgresId: "<postgres-id>", sql: "SELECT count(*) FROM <key_table>")
```

Run a read-only query on a key table to confirm data was restored correctly. Compare row counts against the Heroku source if possible.

Present a health summary after all checks pass.

### Step 7: DNS Cutover (Manual)

Instruct user to:

1. Add CNAME pointing domain to `[service-name].onrender.com`
2. Remove/update old Heroku DNS entries
3. Wait for propagation

## Rollback Plan

If the migration fails at any point:

- **Services created but not working**: Services can be deleted from the Render dashboard (MCP server intentionally does not support deletion). Heroku app is untouched until maintenance mode is enabled.
- **Env vars wrong**: Call `update_environment_variables` with `replace: true` to overwrite, or fix individual vars.
- **Database migration failed**: Render Postgres can be deleted and recreated. Heroku database is read-only during dump (no data loss). If `maintenance_off` is called on Heroku, the original app is fully operational again.
- **DNS already changed**: Revert CNAME to Heroku and disable maintenance mode on Heroku.

Key principle: **Heroku stays fully functional until the user explicitly cuts over DNS.** The migration is additive until that final step.

## Error Handling

- Service creation fails: show error, suggest fixes (invalid plan, bad repo URL)
- Env var migration partially fails: show which succeeded/failed
- Heroku auth errors: instruct `heroku login` or check `HEROKU_API_KEY`
- Render auth errors: check Render API key in MCP config

Referenced files: 6

View saved version →

---
name: render-monitor
description: Monitor Render services in real-time. Check health, performance metrics, logs, and resource usage. Use when users want to check service status, view metrics, monitor performance, or verify deployments are healthy.
license: MIT
compatibility: Requires Render MCP tools or CLI
metadata:
  author: Render
  version: "1.0.0"
  category: monitoring
---

# Monitor Render Services

Real-time monitoring of Render services including health checks, performance metrics, and logs.

## When to Use This Skill

Activate this skill when users want to:
- Check if services are healthy
- View performance metrics
- Monitor logs
- Verify a deployment is working
- Investigate slow performance
- Check database health

## Prerequisites

**MCP tools (preferred):** Test with `list_services()` - provides structured data

**CLI (fallback):** `render --version` - use if MCP tools unavailable

**Authentication:** If you installed the Render plugin (Cursor, Codex, Claude Code), it provides OAuth for MCP — complete the OAuth prompt. For manual MCP clients, use a Render API key. For CLI, verify with `render whoami -o json`.

**Workspace:** `get_selected_workspace()` or `render workspace current -o json`

> **Note:** MCP tools require the Render MCP server. If unavailable, use the CLI for status and logs; metrics and database queries require MCP.

## MCP Setup

If `list_services()` fails, set up the Render MCP server. For detailed per-tool walkthroughs, see **render-mcp**.

**Plugin setup:** If the Render plugin is installed, complete Render OAuth when prompted, then reload your tool and retry `list_services()`.

**Manual MCP setup:** Add the Render MCP server to your AI tool's MCP config:
- **URL:** `https://mcp.render.com/mcp`
- **Auth header:** `Authorization: Bearer <YOUR_API_KEY>`
- **API key:** `https://dashboard.render.com/u/*/settings#api-keys`

After configuring, restart your tool and retry `list_services()`. Then set your workspace with `list_workspaces()` / `get_selected_workspace()`.

---

## Quick Health Check

Run these 5 checks to assess service health:

```
# 1. Check service status
list_services()

# 2. Check latest deploy
list_deploys(serviceId: "<service-id>", limit: 1)

# 3. Check for errors
list_logs(resource: ["<service-id>"], level: ["error"], limit: 20)

# 4. Check resource usage
get_metrics(resourceId: "<service-id>", metricTypes: ["cpu_usage", "memory_usage"])

# 5. Check latency
get_metrics(resourceId: "<service-id>", metricTypes: ["http_latency"], httpLatencyQuantile: 0.95)
```

---

## Service Health

### Check Status

```
list_services()
```

```
get_service(serviceId: "<id>")
```

### Check Deployments

```
list_deploys(serviceId: "<service-id>", limit: 5)
```

| Status | Meaning |
|--------|---------|
| `live` | Deployment successful |
| `build_in_progress` | Building |
| `build_failed` | Build failed |
| `deactivated` | Replaced by newer deploy |

### Check Errors

```
list_logs(resource: ["<service-id>"], level: ["error"], limit: 50)
```

```
list_logs(resource: ["<service-id>"], statusCode: ["500", "502", "503"], limit: 50)
```

---

## Performance Metrics

### CPU & Memory

```
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["cpu_usage", "memory_usage", "cpu_limit", "memory_limit"]
)
```

| Metric | Healthy | Warning | Critical |
|--------|---------|---------|----------|
| CPU | <70% | 70-85% | >85% |
| Memory | <80% | 80-90% | >90% |

### HTTP Latency

```
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_latency"],
  httpLatencyQuantile: 0.95
)
```

| p95 Latency | Status |
|-------------|--------|
| <200ms | Excellent |
| 200-500ms | Good |
| 500ms-1s | Concerning |
| >1s | Problem |

### Request Count

```
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_request_count"]
)
```

### Filter by Endpoint

```
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_latency"],
  httpPath: "/api/users"
)
```

Detailed metrics guide: [references/metrics-guide.md](references/metrics-guide.md)

---

## Database Monitoring

### PostgreSQL Status

```
list_postgres_instances()
get_postgres(postgresId: "<postgres-id>")
```

### Connection Count

```
get_metrics(resourceId: "<postgres-id>", metricTypes: ["active_connections"])
```

### Query Database

```
query_render_postgres(
  postgresId: "<postgres-id>",
  sql: "SELECT state, count(*) FROM pg_stat_activity GROUP BY state"
)
```

### Find Slow Queries

```
query_render_postgres(
  postgresId: "<postgres-id>",
  sql: "SELECT query, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10"
)
```

### Key-Value Store

```
list_key_value()
get_key_value(keyValueId: "<kv-id>")
```

---

## Log Monitoring

### Recent Logs

```
list_logs(resource: ["<service-id>"], limit: 100)
```

### Error Logs

```
list_logs(resource: ["<service-id>"], level: ["error"], limit: 50)
```

### Search Logs

```
list_logs(resource: ["<service-id>"], text: ["timeout", "error"], limit: 50)
```

### Filter by Time

```
list_logs(
  resource: ["<service-id>"],
  startTime: "2024-01-15T10:00:00Z",
  endTime: "2024-01-15T11:00:00Z"
)
```

### Stream Logs (CLI)

```bash
render logs -r <service-id> --tail -o text
```

---

## Quick Reference

### MCP Tools

```
# Services
list_services()
get_service(serviceId: "<id>")
list_deploys(serviceId: "<id>", limit: 5)

# Logs
list_logs(resource: ["<id>"], level: ["error"], limit: 100)
list_logs(resource: ["<id>"], text: ["search"], limit: 50)

# Metrics
get_metrics(resourceId: "<id>", metricTypes: ["cpu_usage", "memory_usage"])
get_metrics(resourceId: "<id>", metricTypes: ["http_latency"], httpLatencyQuantile: 0.95)
get_metrics(resourceId: "<id>", metricTypes: ["http_request_count"])

# Database
list_postgres_instances()
get_postgres(postgresId: "<id>")
query_render_postgres(postgresId: "<id>", sql: "SELECT ...")
get_metrics(resourceId: "<postgres-id>", metricTypes: ["active_connections"])

# Key-Value
list_key_value()
get_key_value(keyValueId: "<id>")
```

### CLI Commands (Fallback)

Use these if MCP tools are unavailable:

```bash
# Service status
render services -o json
render services instances <service-id>

# Deployments
render deploys list <service-id> -o json

# Logs
render logs -r <service-id> --tail -o text          # Stream logs
render logs -r <service-id> --level error -o json   # Error logs
render logs -r <service-id> --type deploy -o json   # Build logs

# Database
render psql <database-id>                           # Connect to PostgreSQL

# SSH for live debugging
render ssh <service-id>
```

### Healthy Service Indicators

| Indicator | Healthy | Warning | Critical |
|-----------|---------|---------|----------|
| Deploy Status | `live` | `update_in_progress` | `build_failed` |
| Error Rate | <0.1% | 0.1-1% | >1% |
| p95 Latency | <500ms | 500ms-2s | >2s |
| CPU Usage | <70% | 70-90% | >90% |
| Memory Usage | <80% | 80-95% | >95% |

---

## References

- **Metrics guide:** [references/metrics-guide.md](references/metrics-guide.md)

## Related Skills

- **render-deploy** — Deploy new applications to Render
- **render-debug** — Diagnose and fix deployment failures
- **render-mcp** — MCP server setup and tool catalog

Referenced files: 1

View saved version →

---
name: render-networking
description: >-
  Connects Render services over the private network—internal DNS, service
  discovery, and cross-service communication. Use when the user needs to wire
  services together, resolve internal hostnames, troubleshoot connectivity
  between services, configure environment isolation, or understand which
  services can reach each other.
license: MIT
compatibility: Render services in the same region and workspace
metadata:
  author: Render
  version: "1.0.0"
  category: networking
---

# Render private networking

Render’s **private network** lets services talk to each other without exposing traffic on the public internet. Use this skill when users need internal connectivity, discovery across scaled instances, or correct URL/port behavior for Blueprints and the Dashboard.

## When to Use This Skill

- Designing or debugging **service-to-service** traffic on Render
- Questions about **internal hostnames**, **internal URLs**, or **Connect > Internal** in the Dashboard
- **Service discovery** across multiple instances (custom load balancing, mesh-style setups)
- **Port limits**, reserved ports, or **multi-port** web services (public vs private)
- **Free-tier** web services and **who can send vs receive** private traffic
- **Environment isolation** (Professional+) or **AWS PrivateLink** for private egress/ingress patterns

For step-by-step architecture examples and Blueprint patterns, see `references/communication-patterns.md`. For failure modes and fixes, see `references/troubleshooting.md`.

## Private Network Basics

Private connectivity is available only when **all** of the following hold:

- Services are in the **same region**
- Services are in the **same workspace**

If either differs, private DNS and internal routing will not connect those services.

### Who can communicate

| Resource | Private inbound | Private outbound | Internal hostname |
|----------|-----------------|------------------|-------------------|
| **Web Service** | Yes (paid tiers; see Free tier below) | Yes | Yes |
| **Private Service** | Yes | Yes | Yes |
| **Background Worker** | No | Yes | No |
| **Cron Job** | No | Yes | No |
| **Workflow Run** | No | Yes | No |
| **Static Site** | — | — | **Not on private network** |
| **Managed Postgres** | Via internal URL (from allowed clients) | N/A (datastore) | Via internal URL |
| **Key Value** | Via internal URL (from allowed clients) | N/A (datastore) | Via internal URL |

**Free-tier Web Services:** They may **send** private traffic to other services, but they **cannot receive** inbound private traffic. Plan upgrades or topology changes apply if a free web service must accept private connections.

Workers, crons, and workflow runs initiate outbound connections (e.g., to internal URLs or private service hostnames) but are **not** reachable by internal hostname for inbound calls.

## Internal Addresses

- Open the service in the Render Dashboard → **Connect** → **Internal** tab for the canonical internal hostname, URL, and connection details.
- Clients often need an **explicit scheme** in code or config, e.g. `http://service-name:port` or `https://...` when TLS applies—do not assume a bare hostname alone is enough for every HTTP client.
- **URL shape:** `http://[internal-hostname]:[port]/path` (adjust scheme/port per service).

## Service Discovery

For services with **multiple instances**, Render exposes a **discovery DNS** name that resolves to **all instance IPs** for that service. The pattern is **`[hostname]-discovery`** (see Dashboard docs for the exact hostname shown for your service).

- **`RENDER_DISCOVERY_SERVICE`** is set in environments where discovery applies; use it with the discovery hostname pattern for scripts and app code that need instance lists.
- **Use case:** Custom load balancing, health aggregation, or any logic that must fan out or pick among instances explicitly instead of a single internal hostname.

See `references/communication-patterns.md` for discovery-oriented patterns.

## Port Rules

- **Maximum 75 open ports** per service.
- **Reserved ports** (do not bind your app to these for normal use): **10000** (public HTTP proxy path), **18012**, **18013**, **19099**.
- **Multi-port Web Services:** Only **one** port receives **public** HTTP traffic; that port must align with the **`PORT`** environment variable. **Additional** ports are for **private network** access only.

When something fails to connect, verify the target is listening on the expected port and that the port is not reserved or blocked by misconfiguration.

## Environment Isolation

On **Professional and higher** workspaces, you can configure **per-environment** rules so private traffic does **not** cross certain environment boundaries. If private calls work in one environment but not another, check workspace **environment isolation** settings before assuming DNS or app bugs.

## AWS PrivateLink

**Professional+** workspaces can use **AWS PrivateLink** to extend private connectivity to or from external AWS VPCs and approved endpoints. This is separate from default service-to-service private DNS; use it when the architecture requires **private** access to Render or from Render to specific AWS resources without the public internet.

## Common Patterns

Short summaries; full diagrams and Blueprint notes live in `references/communication-patterns.md`.

1. **Web gateway + private backends** — Public Web Service terminates HTTP; internal calls use private hostnames and ports to Private Services or internal URLs.
2. **Worker to database** — Background Worker (no internal hostname) connects **outbound** to Postgres or Key Value **internal URLs**.
3. **Microservices** — Private Services (and eligible Web Services) call each other by **internal hostname:port** on the private network.

## References

| Document | Purpose |
|----------|---------|
| `references/communication-patterns.md` | Gateway, worker→DB, mesh, URL construction, Blueprint `fromService`, discovery load balancing, private health checks |
| `references/troubleshooting.md` | DNS, ports, region/workspace, free tier, protocol, resolver, environment isolation |

## Related Skills

- **render-web-services** — Public web services, `PORT`, and HTTP behavior
- **render-private-services** (planned) — Private Service–specific setup and scaling
- **render-blueprints** — `render.yaml`, `fromService`, and multi-service wiring

Referenced files: 2

View saved version →

---
name: render-postgres
description: >-
  Sets up and optimizes Managed PostgreSQL on Render—connection strings
  (internal vs external), creation constraints, storage autoscaling, connection
  limits, high availability, read replicas, backups, and MCP inspection. Use
  when the user
  mentions Postgres, PostgreSQL, Render database, connection string, DATABASE_URL,
  backups, snapshots, replicas, HA, disk storage, connection pooling, or
  troubleshooting DB connectivity.
license: MIT
compatibility: Render Managed Postgres (any plan)
metadata:
  author: Render
  version: "1.0.0"
  category: data
---

# Render Managed PostgreSQL

This skill covers **Managed Postgres on Render**: how to connect, what cannot change after creation, storage behavior, limits, HA, replicas, and safe deletion. Deep dives live under `references/`.

## When to Use

Apply this skill when the user:

- Configures **Postgres** for an app on Render (URLs, TLS, pooling)
- Creates or changes a **database**, **plan**, **disk**, or **replicas**
- Asks about **backups**, **PITR**, **exports**, or **deleting** a database
- Hits **connection limits**, **SSL errors**, or **latency** between services and DB
- Authors **Blueprint** `databases` / `readReplicas` or wires `fromDatabase`

For deploy flows and Blueprint basics, see **render-deploy** and **render-blueprints**. For private networking between services, see **render-networking**. For env var patterns, see **render-env-vars**.

## Connection Patterns

Render exposes **two connection URLs** for the same logical database:

| URL | Use when | TLS |
|-----|----------|-----|
| **Internal** | App or service on Render in the **same region and workspace** | Not required (private network) |
| **External** | Local development, CI, or tools outside Render | **Required** (TLS 1.2+) |

**Always prefer the internal URL for Render-hosted apps** so traffic stays on Render’s network and avoids extra latency and public egress patterns.

- **IP allow list** applies to **external** access only. Same-region Render services use the **internal** URL regardless of the allow list.
- **External** clients must use TLS; misconfigured clients often show SSL handshake or `sslmode` errors.

URL formats, Dashboard locations, Blueprint `fromDatabase`, pooling, and common mistakes: `references/connection-guide.md`.

## Creation and Setup

- **Instance display name**: Can be changed later (where the Dashboard allows renaming the resource).
- **Immutable after creation**: `databaseName`, database **user**, **region**, **PostgreSQL major version**. Plan these before create; changing them requires a new database and migration.
- **Storage size**: **1 GB** or **multiples of 5 GB** when provisioning.

Wire apps with Blueprint `fromDatabase` using `property: connectionString` (or `host`, `port`, `user`, `password`, `database` individually). See **render-blueprints**.

### Multiple logical databases

You can run `CREATE DATABASE new_db;` in `psql` on the same instance. **Host, port, and credentials stay the same**; only the **database name in the URL path** changes (e.g. `.../myapp` vs `.../new_db`).

## Storage Management

- **Autoscaling**: When disk use reaches roughly **~90%**, Render can grow storage by about **~50%**, rounded up to the **next 5 GB multiple**, up to **16 TB** max.
- **Cannot shrink** disk after an increase.
- **Cooldown**: After a storage increase, you **cannot increase again for 12 hours**.
- **Over limit / unhealthy**: If disk is over the configured limit, the database can become **unhealthy**; Render may **suspend** it until resolved.

Monitor disk and plan exports or cleanup before you hit hard limits. Backup and restore options: `references/backup-and-recovery.md`.

## Connection Limits

Maximum connections depend on **instance RAM** (current-generation plans):

| RAM | Max connections (typical) |
|-----|---------------------------|
| Under 8 GB | 100 |
| 8 GB | 200 |
| 16 GB | 300 |
| 32 GB and above | 500 |

**Legacy** database plans may have **lower** limits; confirm in the Dashboard or API for the specific plan.

Render does **not** provide a built-in pooler; use **application-side pooling** (framework pools, PgBouncer, pgpool, etc.). Limits are **hard**—exhausting them causes connection errors. More detail: `references/connection-guide.md` and `references/performance-tuning.md`.

## High Availability

**High availability (HA)** is available when:

- Workspace is **Professional** or higher, **and**
- Database plan is **Pro** or higher, **and**
- **PostgreSQL 13+**

**Instance type changes** cause **brief downtime**. With HA, downtime is typically **less** than **without HA** (often on the order of **minutes** without HA—exact duration depends on plan and operation).

**One-way migration off legacy types**: After moving to current-generation instance types, you **cannot** move back to **legacy** instance types.

## Read Replicas

- Up to **5 read replicas** per database.
- In Blueprints, declare replicas under **`readReplicas`** as a **list of names**.
- **CAUTION — declarative sync**:
  - An **empty** `readReplicas` list can **destroy all** existing replicas.
  - **Name mismatches** between the Blueprint and live replicas can **create** new replicas and **remove** replicas whose names are no longer listed.

Always treat `readReplicas` as **authoritative** desired state, not additive-only.

## Useful MCP Commands

Use the Render MCP tools (names may vary slightly by integration; align with your server’s tool list):

| Goal | Tool / pattern |
|------|----------------|
| List databases | `list_postgres_instances` |
| Instance details | `get_postgres` with `postgresId` |
| Read-only SQL | `query_render_postgres` with `postgresId` and `sql` |
| Connection load | `get_metrics` with `resourceId` (Postgres ID) and `metricTypes: ["active_connections"]` |

`query_render_postgres` runs in a **read-only** transaction and opens a **new connection per query**—do not use it as a substitute for app pooling.

Shorthand (same tools): `list_postgres_instances()`, `get_postgres(postgresId)`, `query_render_postgres(postgresId, sql)`, `get_metrics(resourceId, metricTypes: ["active_connections"])`.

## Deleting and Data Safety

- **Backups and snapshots are not retained** after you **delete** the database. **Export first** (`pg_dump`, Dashboard restore workflow from existing backups, etc.).
- Before destructive actions, confirm retention and recovery paths in `references/backup-and-recovery.md`.

## References

| Document | Contents |
|----------|----------|
| `references/connection-guide.md` | Internal vs external URLs, SSL, allow list, Blueprint wiring, pooling, multi-database URLs, troubleshooting |
| `references/backup-and-recovery.md` | Snapshots, PITR, `pg_dump` / `pg_restore`, restore flows, deletion, cross-region |
| `references/performance-tuning.md` | `pg_stat_statements`, indexes, bloat, `EXPLAIN ANALYZE`, metrics, scaling |

## Related Skills

- **render-deploy** — End-to-end deploy, services, and MCP/Dashboard flows
- **render-blueprints** — `databases`, `fromDatabase`, `readReplicas`, immutable fields
- **render-networking** — Private services, regions, and how traffic routes between resources
- **render-env-vars** — Storing `DATABASE_URL` and secret wiring patterns

Referenced files: 3

View saved version →

---
name: render-private-services
description: >-
  Configures Render private services—internal-only apps that accept traffic
  exclusively from other Render services over the private network. Use when
  the user needs an internal API, microservice, gRPC server, sidecar, or any
  service that should not be publicly accessible. Also use when choosing
  between a private service and a background worker.
  Trigger terms: private service, pserv, internal service, internal API,
  microservice, gRPC, not public, private network service.
license: MIT
compatibility: Render private services (paid plans)
metadata:
  author: Render
  version: "1.0.0"
  category: compute
---

# Render Private Services

Private services are identical to web services except they have **no public URL**. They are reachable only by other Render services on the same **private network** (same region + workspace). Use them for internal APIs, microservices, gRPC servers, sidecar processes, and anything that should never face the internet.

## When to Use

- Building an **internal API** or **microservice** behind a public gateway
- Running a **gRPC**, **TCP**, or other non-HTTP server that only your services call
- Deploying infrastructure components (**Elasticsearch**, **ClickHouse**, **RabbitMQ**)
- Choosing between a **private service** and a **background worker**

For public-facing HTTP services, use **render-web-services**. For services that don't receive any traffic, use **render-background-workers**.

## Private Service vs Background Worker

| Criterion | Private Service | Background Worker |
|-----------|----------------|-------------------|
| Binds to a port | **Yes** (required) | No |
| Receives private network traffic | **Yes** | No |
| Sends outbound traffic | Yes | Yes |
| Has internal hostname | **Yes** | No |
| Use case | Internal APIs, gRPC, TCP servers | Queue consumers, async processors |

**Rule of thumb:** If the process **listens on a port** and other services call it, it's a private service. If it **pulls work from a queue** and never receives requests, it's a background worker.

## How Private Services Work

- No `onrender.com` subdomain—not reachable from the internet
- Reachable at `<service-name>:<port>` on the private network by services in the same region and workspace
- Can listen on **any port** (except restricted system ports)—not limited to HTTP or port 10000
- Supports **any protocol**: HTTP, gRPC, TCP, WebSocket, custom binary protocols
- Same build/deploy lifecycle as web services (build command, start command, pre-deploy, health checks via the private network)
- Supports persistent disks, scaling, Docker runtime—same capabilities as web services

## Connecting to a Private Service

Other services reference a private service via its **internal hostname and port**:

```
http://<service-name>:<port>
```

In Blueprints, wire the address using `fromService`:

```yaml
- key: INTERNAL_API_URL
  fromService:
    name: my-api
    type: pserv
    property: hostport
```

Available `fromService` properties for `pserv`:

| Property | Value |
|----------|-------|
| `host` | Internal hostname (e.g. `my-api`) |
| `port` | Port the service listens on |
| `hostport` | `host:port` combined (e.g. `my-api:10000`) |

You can also reference a specific env var from the private service using `envVarKey` instead of `property`.

## Port Binding

Private services **must bind to at least one port**. If your process does not need to receive traffic, create a background worker instead.

- Bind to `0.0.0.0` (not `127.0.0.1` or `localhost`)
- The `PORT` env var defaults to `10000`, but you can listen on any non-restricted port
- For non-HTTP protocols (gRPC, TCP), configure your server on the desired port and tell consumers the `hostport`

## Blueprint Configuration

```yaml
services:
  - type: pserv
    name: internal-api
    runtime: node
    region: oregon
    plan: starter
    buildCommand: npm ci && npm run build
    startCommand: npm start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: db
          property: connectionString
```

### Microservices pattern (gateway + internal services)

```yaml
services:
  - type: web
    name: gateway
    runtime: node
    plan: starter
    region: oregon
    buildCommand: npm ci && npm run build
    startCommand: npm start
    envVars:
      - key: USER_SERVICE_URL
        fromService:
          name: user-service
          type: pserv
          property: hostport
      - key: BILLING_SERVICE_URL
        fromService:
          name: billing-service
          type: pserv
          property: hostport

  - type: pserv
    name: user-service
    runtime: node
    plan: starter
    region: oregon
    buildCommand: npm ci
    startCommand: node server.js
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: db
          property: connectionString

  - type: pserv
    name: billing-service
    runtime: python
    plan: starter
    region: oregon
    buildCommand: pip install -r requirements.txt
    startCommand: gunicorn billing:app
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: db
          property: connectionString
```

## References

| Document | Contents |
|----------|----------|
| `references/patterns.md` | Microservice topology, gRPC setup, sidecar patterns, health checks for private services |

## Related Skills

- **render-web-services** — Public HTTP services
- **render-networking** — Private network, DNS, service discovery
- **render-background-workers** — Services that don't receive traffic
- **render-blueprints** — Full `render.yaml` schema, `fromService` wiring
- **render-scaling** — Instance types and autoscaling for private services

Referenced files: 1

View saved version →

---
name: render-scaling
description: >-
  Scales Render services—configures autoscaling targets, chooses instance
  types, sets manual instance counts, and optimizes cost. Use when the user
  needs to handle more traffic, set up autoscaling, pick the right instance
  type, reduce costs, or troubleshoot scaling behavior like slow scale-down or
  stuck instances.
license: MIT
compatibility: Render web services, private services, and background workers
metadata:
  author: Render
  version: "1.0.0"
  category: operations
---

# Render Scaling

This skill covers how to scale **Web Services**, **Private Services**, and **Background Workers** on Render: manual instance counts, **Professional+** autoscaling, plan (instance type) choices, and platform limits. Deeper tables and tuning guidance live under `references/`.

## When to Use

- Setting or changing **instance count** (Dashboard, CLI, API, or Blueprint)
- Configuring **autoscaling** (min/max, CPU and memory targets)
- Choosing **vertical** (plan) vs **horizontal** (more instances) scaling
- Understanding **constraints** (disks, static sites, cron/workflows, 100-instance cap)
- **Cost** implications of multi-instance and per-second billing
- **Blueprint** fields: `numInstances`, `scaling`, `plan`

## Manual Scaling

- Set **instance count** from **1 to 100** via the **Dashboard**, **CLI**, or **API**.
- **All instances share the same instance type** (plan); you cannot mix plans on one service.
- Changes apply **immediately**: Render **provisions** new instances and **deprovisions** excess capacity as needed.

## Autoscaling

- Available on **Professional and higher** workspaces only.
- Configure **minimum** and **maximum** instances and targets for **CPU** and/or **memory** utilization (**1–90%** each).
- **At least one metric must be enabled** (CPU or memory). If **both** CPU and memory autoscaling toggles are **off**, autoscaling is **disabled**.
- If **both** manual instance settings and autoscaling are configured, **autoscaling wins**—manual count does not override the scaling policy in effect.

## Autoscaling Formula

Render computes a candidate instance count from utilization vs target:

`new_instances = ceil(current_instances * (current_utilization / target_utilization))`

- When **both** CPU and memory targets are set, the platform uses the **larger** of the two `new_instances` values (the more conservative scale-out).

## Scaling Constraints

| Constraint | Behavior |
|------------|----------|
| **Per service** | **Maximum 100** instances |
| **Persistent disk** | **Cannot** scale to multiple instances—**single instance only** |
| **Static sites** | **Not** scalable (served by CDN) |
| **Cron jobs & Workflows** | Scaling model **does not apply** (different execution model) |

## Scale-Down Behavior

- **Scale-up** is **immediate** when utilization supports it.
- **Scale-down** waits **a few minutes** after conditions allow reduction (**spike protection**). This reduces **flapping** from brief load spikes.

## Instance Types

- In Blueprints, the instance type is the **`plan`** field (e.g. `standard`, `pro`).
- Options span **free** / **starter** through **standard**, **pro**, **pro_plus**, **pro_max**, **pro_ultra**—each with defined **CPU** and **RAM** (see `references/instance-types.md`).

### Vertical vs Horizontal

| Need | Approach | When |
|------|----------|------|
| More throughput | **Horizontal** (add instances) | Stateless services, request-based workloads |
| More RAM/CPU per process | **Vertical** (upgrade **plan**) | Memory-intensive or single-threaded apps |
| Both | **Combine** | Right-size plan, then scale out for traffic |

## Cost Patterns

- **Per-second billing**; **no separate fee** for scaling actions.
- You pay roughly for **compute time × number of running instances** (see [Render pricing](https://render.com/pricing) for current rates).
- **Right-size** by monitoring **CPU and memory** utilization (see **render-monitor**).

## Blueprint Configuration

**Manual instance count:**

```yaml
numInstances: 3
```

**Autoscaling:**

```yaml
scaling:
  minInstances: 1
  maxInstances: 10
  targetCPUPercent: 70
  targetMemoryPercent: 80
```

**Instance type (plan):**

```yaml
plan: standard
```

Do not rely on `numInstances` to cap autoscaling when a `scaling` block is present—**autoscaling takes precedence**. Preview behavior for scaling is detailed in `references/autoscaling-guide.md`.

## References

| Topic | File |
|--------|------|
| Plan names, CPU/RAM, flexible vs non-flexible, free tier | `references/instance-types.md` |
| Enabling autoscaling, targets, min/max, mistakes, previews | `references/autoscaling-guide.md` |

## Related Skills

- **render-web-services** — Web Service settings, disks, deploy lifecycle
- **render-background-workers** — Worker-specific configuration and scaling context
- **render-blueprints** — Full Blueprint schema and field reference
- **render-monitor** — Metrics, logs, and utilization for right-sizing

Referenced files: 2

View saved version →

---
name: render-static-sites
description: >-
  Deploys and configures static sites on Render's global CDN—build commands,
  publish paths, SPA routing, redirects, custom headers, and PR previews. Use
  when the user needs to deploy a static site, set up a React/Vue/Hugo/Gatsby
  frontend, configure SPA fallback routing, add redirect rules, customize
  response headers, or choose between a static site and a web service for
  their frontend.
  Trigger terms: static site, CDN, SPA, single-page app, React deploy,
  Vue deploy, Hugo, Gatsby, Docusaurus, Jekyll, staticPublishPath.
license: MIT
compatibility: Render static sites (free tier available)
metadata:
  author: Render
  version: "1.0.0"
  category: compute
---

# Render Static Sites

Deploys static frontends (React, Vue, Hugo, Gatsby, Docusaurus, Jekyll, etc.) to Render's global CDN with automatic TLS, Brotli compression, HTTP/2, and DDoS protection. Free tier available.

## When to Use

- Deploying a **static site or SPA** (no server-side rendering)
- Choosing between a **Static Site** and a **Web Service** for a frontend
- Configuring **SPA fallback routing**, **redirects/rewrites**, or **custom headers**
- Setting up **PR preview environments** for a static site
- Troubleshooting **build failures** or **stale content** on a CDN-hosted site

For SSR frameworks (Next.js, Nuxt, SvelteKit) that need a running server, use **render-web-services** instead. For Blueprint authoring, see **render-blueprints**.

## Static Site vs Web Service

| Need | Use | Why |
|------|-----|-----|
| Pure HTML/CSS/JS, SPA, docs, blog | **Static Site** | Free, global CDN, instant cache invalidation |
| SSR (Next.js `next start`, Nuxt server) | **Web Service** | Needs a running Node/Python/etc. process |
| Static export from SSR framework | **Static Site** | If the framework supports full static export (`next export`, `nuxt generate`) |
| API backend | **Web Service** | Static sites cannot run server code |

**Key constraint:** Static sites are **not on the private network**. They cannot communicate with other Render services over internal hostnames.

## Build and Publish

| Setting | Purpose |
|---------|---------|
| `buildCommand` | Installs dependencies and builds assets (e.g. `npm ci && npm run build`) |
| `staticPublishPath` | Directory of built output to serve (e.g. `build`, `dist`, `public`) |

Render auto-detects and installs dependencies. Set `SKIP_INSTALL_DEPS=true` to handle installation yourself in the build command.

### Common frameworks

| Framework | Build command | Publish path |
|-----------|--------------|--------------|
| Create React App | `npm ci && npm run build` | `build` |
| Vite (React/Vue/Svelte) | `npm ci && npm run build` | `dist` |
| Next.js (static export) | `npm ci && next build` | `out` |
| Nuxt (static) | `npm ci && nuxt generate` | `.output/public` |
| Hugo | `hugo --minify` | `public` |
| Gatsby | `npm ci && gatsby build` | `public` |
| Docusaurus | `npm ci && npm run build` | `build` |
| Jekyll | `bundle exec jekyll build` | `_site` |
| Astro | `npm ci && astro build` | `dist` |

## SPA Routing and Redirects

Single-page apps need a catch-all rule so the CDN serves `index.html` for all routes instead of returning 404.

Configure **Redirect/Rewrite Rules** in the Dashboard (Settings > Redirects/Rewrites) or via the Blueprint `routes` field:

```yaml
routes:
  - type: rewrite
    source: /*
    destination: /index.html
```

For multi-path redirects (e.g. old blog URLs), add specific rules **above** the catch-all so they take priority.

See `references/routing-and-headers.md` for redirect types, header rules, and caching patterns.

## Custom Response Headers

Add security and performance headers from the Dashboard (Settings > Headers) or the Blueprint `headers` field:

```yaml
headers:
  - path: /*
    name: X-Frame-Options
    value: DENY
  - path: /assets/*
    name: Cache-Control
    value: public, max-age=31536000, immutable
```

## PR Previews

Static sites support automatic PR previews—each pull request gets a unique URL with the built site.

- Enable in Dashboard: Settings > PR Previews
- Blueprint: set `previews.generation` to `automatic` or `manual`
- Preview URLs follow the pattern `<service>-<pr-id>.onrender.com`

## Blueprint Configuration

```yaml
services:
  - type: web
    runtime: static
    name: my-frontend
    buildCommand: npm ci && npm run build
    staticPublishPath: dist
    routes:
      - type: rewrite
        source: /*
        destination: /index.html
    headers:
      - path: /*
        name: X-Frame-Options
        value: DENY
    previews:
      generation: automatic
```

**Note:** Static sites use `type: web` with `runtime: static` in Blueprints. There is no separate `type: static`.

## CDN and Performance

- **Global CDN** with edge caching worldwide
- **Brotli compression** (better than gzip)
- **HTTP/2** by default
- **Immediate cache invalidation** on every deploy (zero-downtime, atomic deploys)
- **DDoS protection** included free

## Billing

Static sites have a **free tier**. They count against workspace-level monthly included amounts for:

- **Outbound bandwidth** (data served to users)
- **Pipeline minutes** (build time)

## References

| Document | Contents |
|----------|----------|
| `references/routing-and-headers.md` | Redirect types, rewrite rules, header patterns, SPA config |
| `references/framework-configs.md` | Build commands and publish paths for 10+ frameworks |

## Related Skills

- **render-web-services** — For SSR frameworks that need a running server
- **render-blueprints** — Full `render.yaml` schema for static site fields
- **render-domains** — Custom domain and TLS setup
- **render-deploy** — Deploy flows, CLI, MCP operations

Referenced files: 2

View saved version →

---
name: render-web-services
description: >-
  Configures Render web services—port binding, TLS, health checks, custom
  domains, auto-deploy, PR previews, persistent disks, and deploy lifecycle.
  Use when the user needs to set up a web service, fix health check failures,
  add a custom domain, configure zero-downtime deploys, or troubleshoot port
  binding issues.
license: MIT
compatibility: Render web services (native runtimes or Docker)
metadata:
  author: Render
  version: "1.0.0"
  category: compute
---

# Render Web Services

This skill covers **Web Service** behavior on Render: how traffic reaches your process, how deploys go live, and how optional features (domains, disks, auto-deploy) interact. Use it alongside Blueprint and networking skills when wiring `render.yaml` or Dashboard settings.

## When to Use

- Configuring or debugging **port binding**, **PORT**, or **multi-port** web services
- **TLS/HTTPS** expectations at the edge vs inside the container
- **Health checks** blocking or rolling back deploys
- **Custom domains**, DNS, and certificate provisioning
- **Auto-deploy**, **CI-gated deploys**, and **PR preview** generation
- **Persistent disks** and their impact on scaling and zero-downtime
- **Deploy lifecycle**: build, pre-deploy, swap, drain, **rollback**, shutdown delay

Deeper patterns live under `references/` (health checks, domains, deploy phases).

## Port Binding

- Listen on **`0.0.0.0`** (all interfaces). Binding only to **`localhost`** or **`127.0.0.1`** prevents Render’s proxy from reaching your app.
- Use the **`PORT`** environment variable for the HTTP listen port. Render sets it for you; the **default is often `10000`** and you can change the configured value in the service **Settings** in the Dashboard.
- **Reserved ports** (do **not** bind your application to these for normal traffic): **`18012`**, **`18013`**, **`19099`**.

### Multi-port Web Services

- Only **one** port receives **public** HTTP traffic: the port aligned with **`PORT`**.
- **Additional** open ports are reachable on Render’s **private network** only (not from the public internet through the same public URL pattern).

## TLS and HTTPS

- **TLS terminates at Render’s edge.** The edge speaks HTTPS to clients; your process typically receives **plain HTTP** on `PORT`.
- **HTTPS redirect** for clients is handled by the platform; users hitting HTTP are redirected appropriately at the edge.
- **Do not terminate TLS inside the app** for the primary public listener unless you have a rare, explicit need—standard Web Services assume HTTP behind the proxy.

## Health Checks

- Configure a path via **`healthCheckPath`** in a Blueprint or the **Health Check Path** field in the Dashboard.
- Render issues **HTTP GET** requests to that path. Responses must be **`2xx` or `3xx`** for success.
- **Failed health checks** prevent a new deploy from **going live** (the deploy does not succeed in taking production traffic as expected).
- Render probes on a **repeat interval** with a per-request **timeout**; both are **configurable** in service settings (see Dashboard). Failed checks during rollout prevent the new revision from receiving traffic.
- Check frequency, timeouts, and tuning guidance in `references/health-check-patterns.md`.

## Custom Domains

- Point DNS with a **CNAME** to **`[service-name].onrender.com`** (use your service’s hostname from the Dashboard).
- Render **automatically provisions and renews** TLS certificates for verified domains.
- **Apex** (root) domains need provider-specific **CNAME-like** or flattened records where plain CNAME at `@` is unsupported.
- **Wildcard** domains (e.g. `*.example.com`) are supported when configured and verified.
- Multiple custom domains per service are supported; Blueprints can list them under the **`domains`** field.

See `references/custom-domains.md` for Dashboard steps, verification, and troubleshooting.

## Auto-Deploy and PR Previews

- **`autoDeployTrigger`** (Blueprint) / auto-deploy settings control when production deploys run:
  - **`commit`** — deploy on every push to the tracked branch
  - **`checksPass`** — deploy only when required **Git checks** pass
  - **`off`** — **manual** deploys only (Dashboard, CLI, hooks)
- **PR previews** are configured under Blueprint **`previews.generation`** (and related preview settings); generation behavior depends on repo integration and plan.

## Persistent Disks

- Attach disks via the **`disk`** field in a Blueprint (or equivalent Dashboard storage settings).
- A service with an attached persistent disk is **single-instance** only: **horizontal scaling** is not available in that configuration.
- **Zero-downtime deploys are disabled** when a persistent disk is attached—deploys follow a different rollout pattern.
- **Disk size increases** are allowed; **decreases** are not.
- The disk is **not mounted during the build phase**—only at **runtime** in the running service.

## Deploy Lifecycle

Typical flow:

1. **Build** — clone repo, run **`buildCommand`**, produce the runnable artifact/image.
2. **Pre-deploy command** (optional) — runs in the **new** image **before** traffic switches; use for **migrations**. If it **fails**, the deploy is **canceled**.
3. **Deploy** — new instances start; health checks must pass before traffic moves.
4. **Zero-downtime swap** (when applicable) — traffic shifts to new instances; **old instances drain** in-flight work.

- **`maxShutdownDelaySeconds`** (range **1–300**, **default 30**) bounds how long old instances may continue handling requests during drain before shutdown.
- **Rollbacks** — revert to a **previous successful deploy** from the Dashboard.

Full sequence, hooks, filters, and CLI notes: `references/deploy-lifecycle.md`.

## Free Tier Notes

Free Web Services have **separate limits**: e.g. **no custom domains** on the free instance type, and services **spin down after inactivity** (cold starts on next request). Treat free-tier behavior as distinct from paid Web Service defaults when advising on domains, uptime, and scaling.

## References

| Topic | File |
|--------|------|
| Health check design, timeouts, pitfalls | `references/health-check-patterns.md` |
| Domains, DNS, TLS verification | `references/custom-domains.md` |
| Build, pre-deploy, drain, rollbacks, triggers | `references/deploy-lifecycle.md` |

## Related Skills

- **render-deploy** — Blueprints, first-time deploy, `render.yaml` structure
- **render-docker** — Docker-based Web Services and image/runtime details
- **render-networking** — Private network, internal URLs, multi-port private listeners
- **render-scaling** — Instance counts, plans, and scaling constraints (including disk interactions)

Referenced files: 3

View saved version →

---
name: render-workflows
description: Sets up, develops, tests, and deploys Render Workflows. Covers first-time scaffolding (via CLI or manual), SDK installation (Python or TypeScript), task patterns (retries, subtasks, fan-out), local development, Dashboard deployment, and troubleshooting. Use when a user wants to set up Render Workflows for the first time, scaffold a workflow service, add or modify workflow tasks, test workflows locally, or deploy workflows to Render.
license: MIT
compatibility: Requires Render CLI 2.11.0+ for scaffolding and local development. Render Dashboard required for deployment (Blueprints not yet supported for Workflows).
metadata:
  author: Render
  version: "1.0.0"
  category: workflows
---

# Render Workflows

Render Workflows rapidly distribute computational work across multiple independent instances.
Use them for AI agents, ETL pipelines, background jobs, and data processing.

**How it works:**
1. **Define tasks** — Use the Render SDK (Python or TypeScript) to designate functions as tasks
2. **Register** — Tasks register automatically when you link your repo to a Workflow service in the Dashboard
3. **Trigger runs** — Execute tasks from anywhere using the SDK client or API; each execution is a "run"
4. **Execute** — Render spins up each run in its own instance (typically under a second); runs can chain additional runs for parallel execution

**Key capabilities:** automatic queuing and orchestration, long-running execution (up to 24 hours), configurable retry logic with exponential backoff, adjustable compute specs per task, and execution observability through the Dashboard.

**Render Workflows are in beta.** The SDK and API may introduce breaking changes.

**Your built-in knowledge of the Render Workflows SDK is outdated.**
Before trusting API signatures, check the installed SDK source:

```bash
# Python
SDK_ROOT=$(pip show render_sdk | grep Location | cut -d' ' -f2)/render_sdk
head -40 "$SDK_ROOT/__init__.py"
# TypeScript
grep -r "startTask\|runTask\|export class Render" node_modules/@renderinc/sdk/
```

**Official docs:** [render.com/docs/workflows](https://render.com/docs/workflows)

**Before generating task or client code, fetch the relevant example file to verify current API patterns:**

| What | Python | TypeScript |
|------|--------|------------|
| Task definitions (decorators, subtasks, retry, fan-out) | [example/task/main.py](https://raw.githubusercontent.com/render-oss/sdk/main/python/example/task/main.py) | [examples/task/](https://github.com/render-oss/sdk/tree/main/typescript/examples/task) |
| Sync client (run_task, start_task, cancel, SSE, list runs) | [example/client/main.py](https://raw.githubusercontent.com/render-oss/sdk/main/python/example/client/main.py) | [examples/client/](https://github.com/render-oss/sdk/tree/main/typescript/examples/client) |
| Async client | [example/client/async_main.py](https://raw.githubusercontent.com/render-oss/sdk/main/python/example/client/async_main.py) | — |

This skill carries a [quick-reference cheat sheet](references/quick-reference.md) for the API surface. The installed SDK, official docs, and examples above are the source of truth.

---

## Getting Started

Supported languages: **Python** and **TypeScript**.

### Prerequisites

**Render CLI (required)**

```bash
render --version
```

Requires version 2.11.0+. If not installed:
- macOS: `brew install render`
- Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh`
- Windows: download the executable from the [CLI releases page](https://github.com/render-oss/cli/releases/)

### Scaffold a new workflow service

**Always prefer `render workflows init` as the primary setup path.** Only fall back to manual scaffolding if the CLI command is unavailable.

```bash
render workflows init
```

**Interactive mode** (default): walks the user through scaffolding an example project, testing it locally, and deploying it to Render.

**Non-interactive mode**: sets up an example project without prompting.

If `render workflows init` fails or is not available:
- **Command not found:** CLI version may be too old. Run `render --version` and upgrade to 2.11.0+.
- **Command not supported:** fall back to [references/manual-scaffolding.md](references/manual-scaffolding.md) for step-by-step manual setup.

---

## Define Tasks

Guide the user through defining their actual tasks. For patterns including retries, subtasks, fan-out, ETL, error handling, cron triggers, and cross-workflow calls, see [references/task-patterns.md](references/task-patterns.md).

**After adding a task**, verify it registers by starting the local dev server and listing tasks:
```bash
render workflows dev -- <start-command>
# In another terminal:
render workflows tasks list --local
```

If the task doesn't appear, see [Troubleshooting > Task Registration Issues](references/troubleshooting.md#task-registration-issues).

## Local Development

See [references/local-development.md](references/local-development.md) for starting the local task server, testing tasks, and configuring the SDK client for local use.

## Deploy to Render

Workflows are deployed as a **Workflow** service type in the Render Dashboard. **Blueprints (render.yaml) are not yet compatible with Workflows.**

**Deploy checklist:**

- [ ] Code pushed to GitHub, GitLab, or Bitbucket
- [ ] In the [Render Dashboard](https://dashboard.render.com), click **New > Workflow**
- [ ] Link your repository
- [ ] Set **Root Directory** to `workflows/`
- [ ] Configure build and start commands (see table below)
- [ ] Add environment variables (e.g., `RENDER_API_KEY` for tasks that call other workflows)
- [ ] Click **Deploy Workflow**
- [ ] Verify deployment: check the Dashboard for a successful deploy event

| Field | Python | TypeScript |
|-------|--------|------------|
| **Language** | Python 3 | Node |
| **Build Command** | `pip install -r requirements.txt` | `npm install && npm run build` |
| **Start Command** | `python main.py` | `node dist/main.js` |

If the deploy fails, check the service logs in the Dashboard. For common deployment errors, see [Troubleshooting](references/troubleshooting.md). For general deploy debugging, use the **render-debug** skill.

**Running tasks from other services:**

After deployment, trigger tasks from your other Render services using the SDK client.

Python (synchronous):
```python
from render_sdk import Render

render = Render()
result = render.workflows.run_task("my-workflow/hello", ["world"])
print(result.results)
```

Python (asynchronous):
```python
from render_sdk import RenderAsync

render = RenderAsync()
started = await render.workflows.start_task("my-workflow/hello", ["world"])
finished = await started
print(finished.results)
```

TypeScript:
```typescript
import { Render } from "@renderinc/sdk";

const render = new Render();
const started = await render.workflows.startTask("my-workflow/hello", ["world"]);
const finished = await started.get();
console.log(finished.results);
```

The task identifier format is `{workflow-slug}/{task-name}`, visible on the task's page in the Dashboard.

Workflows do not have built-in scheduling. To trigger tasks on a schedule, use a Render cron job with the SDK client. For cron and cross-workflow examples, see [references/task-patterns.md](references/task-patterns.md).

---

## Constraints and Limits

| Constraint | Limit | Notes |
|------------|-------|-------|
| Arguments and return values | Must be JSON-serializable | No class instances, functions, etc. |
| Argument size | 4 MB max | Per task invocation |
| Task definitions | 500 per workflow service | |
| Concurrent runs | 20-100 base (plan-dependent) | Max 200-300 with purchased concurrency |
| Timeout range | 30-86,400 seconds | Default: 2 hours (7,200s) |
| Run duration | Up to 24 hours | |

### Instance Types

| Plan | Specs |
|------|-------|
| `starter` | 0.5 CPU / 512 MB |
| `standard` (default) | 1 CPU / 2 GB |
| `pro` | 2 CPU / 4 GB |
| `pro_plus` | 4 CPU / 8 GB |
| `pro_max` | 8 CPU / 16 GB |
| `pro_ultra` | 16 CPU / 32 GB |

`pro_plus`, `pro_max`, and `pro_ultra` require requesting access. Set via the `plan` task option.

For current pricing, see [Limits and Pricing for Render Workflows](https://render.com/docs/workflows-limits).

---

## References

- **Quick-reference cheat sheet:** [references/quick-reference.md](references/quick-reference.md) (API surface, env vars, error types)
- **Task patterns:** [references/task-patterns.md](references/task-patterns.md)
- **Local development:** [references/local-development.md](references/local-development.md)
- **Troubleshooting:** [references/troubleshooting.md](references/troubleshooting.md)
- **Manual scaffolding (fallback):** [references/manual-scaffolding.md](references/manual-scaffolding.md)
- **Official docs:** [render.com/docs/workflows](https://render.com/docs/workflows)
- **Starter template (Python):** [render-examples/workflows-template-python](https://github.com/render-examples/workflows-template-python)
- **Starter template (TypeScript):** [render-examples/workflows-template-ts](https://github.com/render-examples/workflows-template-ts)
- **SDK repo:** [github.com/render-oss/sdk](https://github.com/render-oss/sdk)

## Related Skills

- **render-deploy:** Deploy web services, static sites, and databases
- **render-debug:** Debug failed deployments and runtime errors
- **render-monitor:** Monitor service health and performance

Referenced files: 5