Render Disks

RenderOfficialCreated by Render

Skill
Tool integration
Cloud and DevOps
MIT
No issues found

From the author

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.

— the description by Render

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The render-disks skill provides guidance on attaching and managing persistent disks for Render web services, private services, and background workers. Because Render's default filesystem is ephemeral, this skill helps users configure persistent storage for stateful applications like self-managed databases or file upload handlers. It emphasizes the architectural implications of using disks, specifically that disk-backed services are limited to a single instance and cannot support horizontal scaling or zero-downtime deployments. The skill includes a mandatory documentation-retrieval workflow to ensure users always reference the most current platform constraints, pricing, and configuration requirements.

What it does

Configures persistent disk attachment for Render services via Blueprints.
Defines mount paths for persistent file storage.
Provides guidance on sizing disks and managing capacity increases.
Outlines procedures for snapshotting and restoring disk data.
Explains the impact of persistent disks on service scaling and deployment strategies.
Enforces a retrieval workflow for up-to-date platform documentation.

When to use it

When you need to persist files across service restarts and redeployments.
When hosting self-managed databases or stateful infrastructure on Render.
When troubleshooting why a service cannot scale horizontally or perform zero-downtime deploys.
When planning to restore data from a disk snapshot.
When determining if a service requires persistent storage versus managed database alternatives.

Advantages

Ensures persistent data retention on an otherwise ephemeral platform.
Provides clear architectural boundaries for stateful service design.
Prevents common pitfalls by highlighting single-instance constraints.
Promotes the use of official, up-to-date documentation for platform-specific limits.

Usage examples

“How do I add a 10GB persistent disk to my Render web service in my render.yaml?”: The agent provides the correct YAML schema for the disk block, including the required name, mountPath, and sizeGB fields, while warning about the resulting single-instance limitation.
“Why is my service failing to perform zero-downtime deploys?”: The agent identifies that the presence of a persistent disk forces a single-instance configuration, which inherently disables zero-downtime deployment capabilities.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/render-oss/render-disks/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip render-disks.zip -d .agents/skills

Documentation by Render

Render Persistent Disks

Persistent disks preserve files written beneath a service's configured mount path across deploys and restarts.

Before designing, configuring, resizing, transferring data to, snapshotting, restoring, or troubleshooting a disk, read references/persistent-disks.md.

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 a disk snapshot

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

Core Decisions

Render's default filesystem is ephemeral. Only files written beneath a disk's mount path persist across deploys and restarts.
A disk-backed service is single-instance: it cannot use horizontal scaling or zero-downtime deploys.
If file storage must be shared by scaled instances, use external object storage such as S3 or R2. Use Render Postgres for relational data and Render Key Value for managed cache or queue state.
Choose the smallest current disk size that accommodates observed usage because capacity can increase but cannot decrease. For a small upload service, 1–5 GB is a reasonable starting range when supported by the current limits.

Blueprint Setup

For a native Node.js upload service, mount a subdirectory such as /opt/render/project/src/uploads, not the source root itself, and configure the application to write uploads there:

services:
  - type: web
    name: uploads
    runtime: node
    buildCommand: npm ci
    startCommand: npm start
    disk:
      name: uploads-data
      mountPath: /opt/render/project/src/uploads
      sizeGB: 5

Fetch the current disk documentation and Blueprint specification through references/persistent-disks.md before finalizing the mount path or size.

Database Backups and File Recovery

Do not use a disk snapshot to recover a self-managed database such as MySQL: a filesystem snapshot can restore an inconsistent or corrupted database state. Use database-native backups such as mysqldump and test their restore procedure. Move backup files off the service with a currently supported transfer method such as SCP with SSH or Magic-Wormhole. Snapshot restores replace the entire disk and permanently discard changes made after the selected snapshot.

References

Document	Contents
`references/persistent-disks.md`	Current disk constraints, configuration, sizing, snapshots, restores, and transfers

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)

Current documentation retrieval

Whenever this skill directs you to consult current Render documentation:

Retrieve the linked Markdown document directly with an available URL-fetching tool or HTTP client, such as curl. Do not substitute web-search summaries for the document.
Confirm that retrieval succeeded and returned the expected document, then read its contents. Saving a file or printing its path is not sufficient.
If the request fails or your tool cannot read the Markdown response, open and read the linked HTML version instead.
If neither version can be retrieved, disclose that the current reference is unavailable and follow any topic-specific fallback in the skill. Use bundled guidance only for stable constraints, and do not guess at changeable platform details.

When a task requires multiple references, apply this workflow to each one and distinguish the documents you verified from those that remain unavailable.

Files

ATTRIBUTION.mdAdded by AutoGineer878 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md4.7 KiB
references/persistent-disks.md4.5 KiB

references/persistent-disks.md

Persistent disks

Use this guidance only for service-attached persistent disks and for architecture or configuration decisions directly affected by them. Do not apply it to Render Postgres or Key Value storage, object storage, build caches, or ordinary ephemeral filesystem tasks.

By default, a Render service's filesystem is ephemeral. Files created or changed at runtime are lost when the service is redeployed or restarted. Use a persistent disk only when a supported service must retain local filesystem data across those events.

Before designing, configuring, or troubleshooting a persistent disk, fetch the current documentation:

Using the documentation-retrieval workflow in the root SKILL.md, retrieve and read the Markdown reference or its HTML version.

Read the relevant sections before relying on details that can change, including supported service types, size limits and pricing, mount-path restrictions, snapshot cadence and retention, transfer methods, and current scaling or deployment limitations. If the document cannot be fetched, do not guess those details from memory.

A persistent disk belongs to one service and is mounted at one absolute path. Only files written under that mount path persist; the rest of the service filesystem remains ephemeral. Make sure the application writes every intended durable file beneath the configured mount path. A disk is not shared storage, and another service cannot access it.

Under the documented generally available behavior, a disk-backed service runs as a single instance and cannot use autoscaling or zero-downtime deploys. During a deploy, Render stops the existing instance before starting its replacement, so expect a short interruption. If the workload needs horizontal scaling, shared state, or stronger availability, use an external or managed datastore instead of a service-attached disk.

The disk is available only to the running service. Builds, pre-deploy commands, and one-off jobs run on separate compute and cannot access it. Do not design a build step, pre-deploy command, or one-off job that depends on files stored on the mounted disk.

The documented supported service types are paid web services, private services, and background workers. For other workload types, use an appropriate external datastore or reconsider the service architecture rather than assuming a disk can be attached.

Disk capacity can be increased but not decreased. Confirm current limits and pricing in the fetched documentation, and choose capacity using observed usage plus reasonable headroom.

Treat attaching, resizing, or restoring a disk as a stateful mutation. After attaching, verify that the service deploys successfully and that reads and writes use the mounted path.

Snapshots are a disaster-recovery mechanism, not a substitute for application-consistent database backups. A snapshot restore replaces the entire disk; it cannot restore individual files, and it discards changes made after that snapshot. Do not use a disk snapshot to recover a custom database, because a filesystem-level snapshot can restore the database into an inconsistent or corrupted state. Use the database engine's native backup and restore tools instead. Check the current documentation before promising a particular snapshot schedule, retention period, or restore procedure.

Mount paths must be absolute and must satisfy Render's current restrictions. Fetch the documentation instead of reproducing its forbidden-path list or runtime-specific path suggestions from memory. When declaring a disk in a Blueprint, also fetch the current Blueprint specification and follow its disk schema rather than relying on remembered syntax.

Storage-specific guidance

Persistent disk data is encrypted at rest.
Expect the service to restart when restoring a snapshot, in addition to the destructive replacement of disk contents described above.
Disk billing is based on provisioned capacity rather than used capacity. Confirm the current rate and billing behavior in the fetched documentation before estimating cost.

Prefer a managed or external store when the workload does not require single-service local filesystem persistence:

Need	Prefer
Managed relational database	Render Postgres
Managed cache or queue	Render Key Value
Large or shared file storage	External object storage
Temporary build artifacts	The default ephemeral build filesystem

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

The author says: Render paid web services, private services, and background workers

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Render

Publisher

Render (Official)

Source

render-oss/skills · skills/render-disks · commit b985a63

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Render.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download render-disks.zip