AutoGineer
Generated banner for Render Background Workers
Generated logo for Render Background Workers

Render Background Workers

RenderOfficialCreated by Render

  • Skill
  • Tool integration
  • Cloud and DevOps
  • MIT
  • Low risk
Download ZIP

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/render-oss/render-background-workers/download

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

FrameworkLanguageQueue backendNotes
CeleryPythonKey ValueMost common Python task queue
SidekiqRubyKey ValueStandard for Rails
BullMQNode.jsKey ValueModern Node queue
AsynqGoKey ValueGo async task processing
ObanElixirPostgres (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

NeedUseWhy
Always-on queue consumerBackground WorkerPolls continuously; long-lived process
Periodic scheduled taskCron JobRuns on a schedule, exits; 12h max per run
Distributed parallel computeWorkflowEach run gets its own instance; fan-out patterns
High-volume or bursty jobsWorkflowScales 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

TopicFile
Celery, Sidekiq, BullMQ, Asynq, Oban setup + YAMLreferences/queue-framework-setup.md
SIGTERM, maxShutdownDelaySeconds, per-language patternsreferences/graceful-shutdown.md
Deploy lifecycle, shutdown, restart, and verificationreferences/deployments.md
Private-network scope, internal addresses, and troubleshootingreferences/private-networking.md
Service-type selection and execution modelsreferences/service-types.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

<!-- shared:documentation-retrieval -->

Current documentation retrieval

Whenever this skill directs you to consult current Render documentation:

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

  2. Confirm that retrieval succeeded and returned the expected document, then read its contents. Saving a file or printing its path is not sufficient.

  3. If the request fails or your tool cannot read the Markdown response, open and read the linked HTML version instead.

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

<!-- /shared:documentation-retrieval -->

Files

references/private-networking.md

<!-- shared:private-networking -->

Private networking

Render services can communicate over a private network without traversing the public internet. Private-network peers must belong to the same workspace and run in the same region. An isolated project environment can additionally block traffic both to and from resources outside that environment, so workspace and region matching alone do not guarantee connectivity.

Before designing, configuring, or troubleshooting private-network communication, fetch the current Render private-network reference:

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

Read the relevant sections. Confirm current service-type capabilities, port restrictions, environment-isolation behavior, discovery-hostname guidance, and plan requirements instead of relying on a memorized catalog.

Web services and private services have internal hostnames and can receive private-network traffic. A private service must bind at least one port; use a background worker instead when a workload does not need to accept inbound connections. Render Postgres and Key Value instances provide internal connection URLs. Workflows, background workers, and cron jobs can initiate private-network connections but do not have an internal address for receiving them. Static sites are not on the private network. Free web services can initiate private-network connections but cannot receive them.

Prefer the internal address or URL shown under Connect > Internal in the Render Dashboard. Include the protocol when the client or server requires one; an address such as service:10000 does not by itself establish whether to use HTTP, HTTPS, or another protocol. A process that receives traffic must listen on the intended port and on an interface reachable outside its own container, such as 0.0.0.0, rather than only on loopback.

For Blueprint-managed connections, fetch the current Blueprint specification and use supported service or database references instead of copying a generated hostname, port, credential, or connection string. Web and private services currently expose host, port, and hostport properties. A Blueprint can obtain another service's discovery hostname by referencing that service's RENDER_DISCOVERY_SERVICE environment variable with fromService.envVarKey; the discovery hostname is not a service property. The fetched specification is authoritative for the syntax and supported references.

A service can expose at most 75 ports on the private network. Ports 18012, 18013, and 19099 are unavailable for private-network communication. Port 10000 is not generally blocked: for a web service, private traffic to port 10000 routes to its primary HTTP server even when that server binds to another port. In that case, both port 10000 and the actual primary HTTP port route to the same server.

Use a service's normal internal hostname for ordinary service-to-service traffic. For advanced per-instance communication, each web or private service has a discovery hostname, conventionally formed by appending -discovery to its internal hostname, that resolves to all active instance IP addresses. A service receives its own discovery hostname in RENDER_DISCOVERY_SERVICE. Use DNS APIs that honor the system resolver configuration, and do not persist resolved instance IPs because they can change between deploys. Prefer hostname-based communication unless per-instance addressing or custom load balancing is specifically required.

When a private-network connection fails, verify the workspace, region, project-environment isolation settings, whether the destination service type accepts inbound traffic, the internal hostname or URL, protocol, port, listening interface, current deploy health, and DNS resolution. Do not substitute a public URL or expose a private service merely to bypass a private-network configuration problem.

AWS PrivateLink is a separate Pro-or-higher feature for connecting a Render private network to compatible AWS-hosted systems. Fetch its current documentation before proposing or configuring it; do not treat ordinary Render service-to-service networking and PrivateLink as interchangeable.

<!-- /shared:private-networking -->

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

AutoGineer is not affiliated with or endorsed by Render or Render.

Download ZIP

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