Your First Workflow

Register your first task and trigger its first run.

Welcome to Render Workflows! Follow these steps to register your first and trigger its first .

1. Install the Render CLI

You'll use the Render CLI to create a starter project with our Hello World template.

Use version 2.35.0 or later of the Render CLI.

Use any of the following methods to install the Render CLI or upgrade to the latest version:

Homebrew installation

Run the following commands:

After installation completes, open a new terminal tab and run render with no arguments to confirm.

2. Initialize a starter project

  1. From your machine's development directory, run render workflows init to generate a starter project with your first definition:

    Command not found? Make sure you've upgraded to the latest version of the Render CLI.

  2. The init command prompts you for the following, in order:

    PromptDescription

    Language

    Choose whichever supported language you prefer (currently TypeScript or Python).

    Template

    Choose Hello World for this tutorial.

    Output directory

    The CLI creates a new directory for your project at the specified path (default ./workflows-demo).

    Install project dependencies?

    Choose Yes.

    Initialize a new Git repository?

    Choose Yes.

    Running in non-interactive mode?

    To skip prompts in scripts and agents, you can pass all options directly, like so:

    For details, run render help workflows init.

  3. Commit all of the files in your new project directory to Git:

The anatomy of a workflow

The following excerpts from workflows init starter projects illustrate the bare minimum syntax for defining a workflow:

  • You import task and the TaskContext type from the Render SDK for TypeScript. The template also uses tsx to run TypeScript code.
  • You define by calling task(...) once for each, providing options and a function definition.
    • The function must take a TaskContext object as its first argument. Render provides this object to each task run automatically.
  • No additional initialization is required when using the TypeScript SDK.

3. Push your project

Render will deploy your project by pulling its source from a linked repo on your .

Create a new repository for your project with a supported and push your local repo to it.

4. Create a workflow service

  1. In the Render Dashboard, click New > Workflow:

    Creating a new workflow in the Render Dashboard

    The workflow creation form appears.

  2. Link the repo with your workflow's task definitions.

  3. Complete the remainder of the creation form. See guidance for important fields:

    FieldDescription

    Language
    • Choose Node for TypeScript or Python 3 for Python.
    • Choose Docker if you're deploying a workflow project that builds from a Dockerfile.

    All of your workflow's will execute in the specified region.

    This determines which of your other Render services they can reach over your .

    If you're using the Hello World template from render workflows init, this is the following:

    Otherwise, provide the command that Render should use to install dependencies and build your code.

    You don't provide a build command if you're using Docker.

    If you're using the Hello World template from render workflows init, this is the following:

    Otherwise, provide the command that Render should use to start your workflow.

  4. Click Deploy Workflow. Render kicks off your workflow's first build, which includes registering your tasks.

That's it! After the build completes, your tasks are officially registered. You can view them from your workflow's Definitions page in the Render Dashboard:

Viewing a registered task in the Render Dashboard

5. Trigger a task run

Now that we've registered a task, let's run it! The quickest way to trigger our first run is in the Render Dashboard:

  1. From your workflow's Definitions page, click a task to open its Runs page.

  2. Click Run Task in the top-right corner of the page:

    Running a task in the Render Dashboard

    A dialog appears for providing the task's input arguments:

    Providing input arguments for a task run in the Render Dashboard

  3. Provide the task's input arguments as a JSON array (e.g., [5] for a task that takes a single integer argument, or [] for a task that takes zero arguments).

    You can click Format and Validate to cleanly structure your input and confirm that it's valid JSON.

  4. Click Run task.

    Your new task run appears at the top of the Runs table.

Next steps

Congratulations! You've registered your first workflow task and triggered its first run. Now it's time to start designing your own tasks and triggering runs from application code:

Using Docker

You can optionally build your workflow service from a Dockerfile. As with other Render service types, this is useful if you need to install libraries or perform build-time operations that aren't supported by Render's native language runtimes.

During 4. Create a workflow service, note the following changes:

  1. Set the Language field to Docker.
  2. You do not provide a Build Command (the field is hidden entirely for Docker-based workflows).
  3. Set your service's Start Command to the command that Render should use to start your workflow (e.g., npm start or python main.py).
    • This field is currently always required, even if your Dockerfile defines a CMD/ENTRYPOINT default.
  4. Specify your Dockerfile Path if the Dockerfile isn't in your repo's root directory.

Docker-specific limitations

We'll address these limitations in future releases:

  • Workflows do not currently support pulling a prebuilt Docker image from a container registry.
  • It is not currently possible to create a Docker-based workflow service using the Render CLI or API (Dashboard only).
  • Docker-based workflows do not currently support local execution using the Render CLI's task server.