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

HARD RULE: Your built-in knowledge of the Render Workflows SDK is outdated. Before trusting API signatures, always check the installed SDK source or fetch the official example files listed below. Do not generate task or client code from memory alone.

When to Use

Use this skill when a user wants to:

• Scaffold a new Render Workflows service for the first time (CLI or manual fallback).
• Define or modify workflow tasks — decorators, retries, subtasks, fan-out, ETL patterns, error handling, cron triggers, cross-workflow calls.
• Test workflows locally using render workflows dev.
• Deploy a workflow service to Render via the Dashboard.
• Trigger tasks from other services using the SDK client (sync, async, or TypeScript).
• Troubleshoot task registration, deployment, or runtime issues.

Trigger keywords: render workflows, workflow task, render workflows init, render workflows dev, fan-out, subtask, retry, run_task, start_task, Render SDK.

Prerequisites

Render CLI (required, version 2.11.0+)

Check the installed version:

# Windows PowerShell
render --version

# macOS / Linux
render --version

If not installed or older than 2.11.0:

Supported languages

Python and TypeScript.

Verify SDK API surface before writing code

Before generating task or client code, inspect the installed SDK source to confirm current API signatures:

# Python — locate and inspect the SDK package
SDK_ROOT=$(pip show render_sdk | grep Location | cut -d' ' -f2)/render_sdk
head -40 "$SDK_ROOT/__init__.py"

# TypeScript — search for key exports
grep -r "startTask\|runTask\|export class Render" node_modules/@renderinc/sdk/

Fetch the relevant official example file to verify current API patterns:

Official docs: render.com/docs/workflows

Load references/quick-reference.md when you need a compact API surface cheat sheet (decorators, client methods, env vars, error types). The installed SDK, official docs, and examples above are the source of truth — the cheat sheet is a convenience, not authoritative.

Procedure

1. Scaffold a new workflow service

HARD RULE: Always prefer render workflows init as the primary setup path. Only fall back to manual scaffolding if the CLI command is unavailable or fails.

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:

2. Define tasks

Guide the user through defining their actual tasks using the SDK.

Load references/task-patterns.md when the user needs patterns for: retries, subtasks, fan-out, ETL, error handling, cron triggers, or cross-workflow calls.

After adding or modifying a task, verify it registers:

# Terminal 1 — start the local dev server
render workflows dev -- <start-command>

# Terminal 2 — list registered tasks
render workflows tasks list --local

If the task does not appear in the list, see Troubleshooting > Task Registration Issues.

3. Local development and testing

Load references/local-development.md for full instructions on starting the local task server, testing tasks end-to-end, and configuring the SDK client to point at localhost.

Core loop:

1. Start the dev server: render workflows dev -- <start-command>
2. Trigger tasks locally using the SDK client configured for the local server.
3. Observe logs and outputs in the terminal.
4. Iterate on task code; the dev server picks up changes on restart.

4. Deploy to Render

HARD RULE: Blueprints (render.yaml) are NOT yet compatible with Workflows. Deployment must be done through the Render Dashboard manually.

Deploy checklist:

1. Push code to GitHub, GitLab, or Bitbucket.
2. In the Render Dashboard, click New > Workflow.
3. Link your repository.
4. Set Root Directory to workflows/.
5. Configure build and start commands (see table below).
6. Add environment variables (e.g., RENDER_API_KEY for tasks that call other workflows — use YOUR_KEY as a placeholder, never commit live secrets).
7. Click Deploy Workflow.
8. Verify deployment: check the Dashboard for a successful deploy event.

If the deploy fails, check the service logs in the Dashboard. For common deployment errors, load references/troubleshooting.md. For general deploy debugging, use the render-debug skill.

5. Trigger tasks from other services

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

Python (synchronous):

from render_sdk import Render

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

Python (asynchronous):

from render_sdk import RenderAsync

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

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.

Scheduling: 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, load references/task-patterns.md.

Constraints and Limits

Instance Types

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.

Pitfalls

• Do not trust built-in SDK knowledge. The Render Workflows SDK is in beta and your training data is likely outdated. Always inspect the installed SDK source or fetch the official example files before generating code.
• Blueprints do not work for Workflows. Do not attempt to deploy via render.yaml — use the Dashboard New > Workflow flow.
• Tasks must be JSON-serializable. Arguments and return values cannot include class instances, functions, or other non-serializable objects. The 4 MB per-invocation limit is strict.
• Task not appearing in render workflows tasks list --local? Ensure the dev server is running and the task decorator is correctly applied. See references/troubleshooting.md.
• No built-in scheduling. Do not assume cron-like triggers exist in Workflows. Use a separate Render cron job calling the SDK client.
• 24-hour hard cap on run duration. Long-running tasks that exceed 24 hours will be terminated. Design tasks to checkpoint or split work.
• CLI version must be 2.11.0+. Older CLI versions do not support render workflows init or render workflows dev.
• Windows host notes: The CLI is a standalone executable on Windows — download from the releases page. PowerShell is the primary shell; adjust path separators and quoting accordingly when running bash-style commands from this skill.

Verification

Verify CLI version

render --version
# Expected: >= 2.11.0

Verify local task registration

# Terminal 1
render workflows dev -- <start-command>

# Terminal 2
render workflows tasks list --local
# Expected: list of registered task names including your new task

Verify deployment

1. Open the Render Dashboard.
2. Navigate to your Workflow service.
3. Confirm a successful deploy event appears in the event log.
4. Navigate to the Tasks tab — confirm all expected tasks are listed.
5. Trigger a test run from the Dashboard or via the SDK client and confirm it completes successfully.

Verify SDK client connectivity

# Python — quick smoke test after deploy
from render_sdk import Render

render = Render()
result = render.workflows.run_task("my-workflow/hello", ["world"])
print(result.results)
# Expected: task output printed without errors

References

External resources:

• Official docs: render.com/docs/workflows
• Limits and pricing: render.com/docs/workflows-limits
• Starter template (Python): render-examples/workflows-template-python
• Starter template (TypeScript): render-examples/workflows-template-ts
• SDK repo: 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.