Render Background Workers

RenderOfficialCreated by Render

Skill
Tool integration
Cloud and DevOps
MIT
Low risk

From the author

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, 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.

— the description by Render

AutoGineer summary

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

This skill provides guidance on setting up, configuring, and maintaining background worker services on Render. It covers the architectural requirements for long-running, non-HTTP processes that consume jobs from queues, including integration with Render Key Value, framework-specific setup for tools like Celery and Sidekiq, and critical implementation details for graceful shutdowns to prevent job loss.

What it does

Explains the architecture of Render background workers as non-HTTP, long-running processes.
Provides configuration patterns for connecting workers to Render Key Value as a job broker.
Details how to implement graceful shutdown handlers to ensure in-flight jobs complete during deploys.
Offers guidance on choosing between background workers, Cron Jobs, and Workflows.
Includes Blueprint configuration examples for defining worker services in render.yaml.

When to use it

When you need to process asynchronous jobs using frameworks like Celery, Sidekiq, BullMQ, Asynq, or Oban.
When you need to configure a worker to consume from a queue backend.
When you need to ensure your worker handles SIGTERM signals correctly to avoid data loss during deployments.
When you are deciding whether a background worker is the appropriate service type for your task compared to a Cron Job or Workflow.

Advantages

Prevents job loss and duplication by implementing proper graceful shutdown procedures.
Optimizes resource usage by correctly configuring queue brokers and eviction policies.
Provides clear architectural distinctions between different background processing models on Render.
Standardizes the integration of worker services within Render Blueprints.

Usage examples

“How do I configure a Celery worker on Render?”: The agent provides the necessary Blueprint configuration, including the worker service definition and the environment variable wiring for the Redis-compatible Key Value broker.
“How can I prevent my background jobs from failing during a deployment?”: The agent explains how to implement SIGTERM signal handling and configure maxShutdownDelaySeconds to allow in-flight jobs to finish before the process exits.

Install

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

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

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

Documentation by Render

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.

Before deploying, restarting, or changing shutdown behavior, read references/deployments.md. Before configuring or troubleshooting a worker's outbound private-network connection, read references/private-networking.md. When choosing between a worker, cron job, and Workflow, read references/service-types.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	Key Value	Most common Python task queue
Sidekiq	Ruby	Key Value	Standard for Rails
BullMQ	Node.js	Key Value	Modern Node queue
Asynq	Go	Key Value	Go async task processing
Oban	Elixir	Postgres (not a Key Value queue)	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 without a continuously running worker instance

Graceful Shutdown

Workers should: (1) stop accepting new jobs, (2) finish the current job or checkpoint progress, (3) close connections, (4) exit 0.
Follow references/deployments.md for Render's current drain, signal, and shutdown-delay behavior.

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

Blueprint Configuration

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

services:
  - type: keyvalue
    name: jobs
    plan: starter
    region: oregon
    maxmemoryPolicy: noeviction
    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`
Deploy lifecycle, shutdown, restart, and verification	`references/deployments.md`
Private-network scope, internal addresses, and troubleshooting	`references/private-networking.md`
Service-type selection and execution models	`references/service-types.md`

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

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 AutoGineer917 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md6.8 KiB
references/deployments.md7.9 KiB
references/graceful-shutdown.md3.2 KiB
references/private-networking.md4.3 KiB
references/queue-framework-setup.md4.8 KiB
references/service-types.md4.6 KiB

references/deployments.md

Deployments and health checks

A Render deploy is asynchronous. A successful trigger means only that Render accepted or queued the deploy; it does not mean the new version is live. Before triggering a deploy, confirm the workspace, service, intended source commit or image, and current live deploy. Capture the new deploy ID, monitor it to a terminal state, and do not report success until its status is live and the deployed workload has been verified.

Before configuring or troubleshooting deployments and health checks, fetch the current Render references:

deploys.md (HTML: https://render.com/docs/deploys)
health-checks.md (HTML: https://render.com/docs/health-checks)

Using the documentation-retrieval workflow in the root SKILL.md, retrieve and read both references.

Read the relevant sections of both documents. Confirm current service-type support, command timeouts, health-check thresholds, rollout behavior, and configuration syntax rather than relying on remembered values.

Automatic deployment behavior depends on the service's source and settings. A service linked to a branch through a connected Git provider can deploy on each commit, wait for supported CI checks, or require manual triggers. Services that pull a prebuilt image and services linked by a public Git repository URL require manual deploys; moving a mutable image tag does not itself trigger one. When manually deploying a historical commit, verify whether that trigger method changes automatic-deploy settings. If automatic deploys remain enabled, a later branch update can replace the selected commit.

The normal lifecycle is build command, optional pre-deploy command, then start command and readiness checks. If a command fails or times out, the deploy fails and later steps do not run. A pre-deploy command runs after the build on a separate instance before the new version is deployed. Neither the build nor pre-deploy instance can access an attached persistent disk, and pre-deploy filesystem changes do not carry into the running service. Use pre-deploy for release tasks such as database migrations, not for producing runtime artifacts. Pre-deploy commands are supported for paid web services, private services, and background workers.

Render normally deploys services without downtime by starting the new version before retiring the current one. Web and private services continue routing traffic to the current instances until the new instances are ready. Multi-instance services roll out one instance at a time; if a replacement does not become healthy, Render cancels the rollout and retains or restores the previous version. Attaching a persistent disk disables zero-downtime deploys, so plan explicitly for an interruption.

A workflow deployment has a different completion model. It builds and caches the image used by future task runs and includes a task-registration step, but it does not execute those tasks. After a workflow deploy succeeds, verify that the expected task definitions are registered. Trigger and monitor a task run separately only when execution is intended. For workflow-specific deployment behavior, fetch the current workflow overview:

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

Health checks apply to web services and private services. Both use TCP socket checks by default. Only web services support a configured HTTP health-check path. Render sends an HTTP GET; any 2xx or 3xx response received within five seconds succeeds, while other status codes, timeouts, and connection failures fail. Private services support TCP checks only.

For a new deploy, all new instances must pass their checks at the same time within the current readiness window, documented as 15 minutes, before Render routes traffic to them. For a running service, consecutive failures currently remove an instance from routing after 15 seconds and restart it after 60 seconds. Treat these thresholds as platform behavior, not user-tunable health-check interval settings, and verify them in the fetched reference before relying on exact timing.

Design an HTTP health endpoint to represent readiness for production traffic. Keep it fast and side-effect free. Check critical dependencies only when losing that dependency should make the entire instance unavailable; otherwise a transient dependency failure can unnecessarily remove healthy application capacity. Verify the configured path, response status, response time, listening port, and 0.0.0.0 binding when checks fail.

After traffic moves, Render gives the previous instance a drain period, then sends SIGTERM. The application should stop accepting new work, finish or safely abandon in-flight work, close connections, and exit within its shutdown delay. Ensure the actual application process receives the signal: container entrypoints and shell wrappers should use exec or explicitly forward signals. Render sends SIGKILL if the process remains running after the delay. The documented default shutdown delay is 30 seconds and the usual maximum is 300 seconds, but support varies by service configuration; confirm the current reference and Blueprint or API validation before setting maxShutdownDelaySeconds.

A service restart is a special deploy of the same commit and user-defined environment-variable values as the current running instance. It does not incorporate configuration changes saved after that deploy. Use a standard deploy when pending configuration must take effect.

Only one deploy runs at a time for a service. A workspace's overlapping-deploy policy determines whether a new trigger waits or cancels the in-progress deploy. Do not assume the policy or wait for every intermediate revision: inspect the workspace setting and identify the deploy that actually became live.

Treat rollback as a new deploy based on a retained previous build artifact, not as restoration of the entire service to an earlier point in time. It does not reverse database migrations, messages, external writes, or other side effects from the release, so confirm that the previous application version remains compatible with current external state. Disks and their data are not rolled back, some settings continue using current configuration, mutable image tags can resolve to a different image, and eligible artifacts are retained only for a limited period. Before rolling back, fetch the current rollback reference:

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

Read which configuration comes from the target deploy and which remains current. After the rollback is created, inspect the service's resulting automatic-deploy setting instead of assuming whether it remains enabled, and deliberately restore the intended setting after the underlying issue is resolved.

Deploy hooks are secret credentials that authorize deploys. Never print, commit, or expose their full URLs. Before using one, fetch the current deploy-hook reference:

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

Distinguish an immediately started deploy from a queued one, and continue monitoring the resulting deploy rather than treating the HTTP response as completion.

After a deploy becomes live, verify the behavior appropriate to the service type: make a request to a web or private service, confirm a worker is processing work, confirm a cron job or workflow invocation completes, and inspect recent runtime logs for new errors. If a deploy fails, diagnose the first failed lifecycle stage before retrying.

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 Python

The author says: Render background worker services

Security

What our scanner noticed· Low risk

Instructions that use the network

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-background-workers · 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-background-workers.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Render

Render Background Workers

When to Use

How Workers Work

Queue Framework Overview

Pairing with Key Value

Worker vs Cron vs Workflow

Graceful Shutdown

Blueprint Configuration

References

Related Skills

Current documentation retrieval

Files

references/deployments.md

Deployments and health checks

Requirements and compatibility

Security

Attribution and licence

Related skills

Shipping And Launch

Quantized Export

Deployment Pipeline Design

Gitops Workflow

Spark Environment Setup

Cloud Infrastructure Deployment Engineer

Download ZIP