Skip to main content

Ruby SDK developer guide

This guide walks you through setting up the Temporal Ruby SDK and running your first Workflow. In just a few steps, you'll install the SDK and start a local development server. To validate that your local environment is correctly installed, we will execute a Workflow that will output "Hello, Temporal".

1. Installation​

Install the Temporal SDK using your preferred method.

gem 'temporalio'

This approach is used in Ruby projects that manage dependencies with Bundler.

To install it, add the line to your project's Gemfile and run bundle install in your terminal. Bundler will download and install the gem and its dependencies.

gem install temporalio

Both methods will install the same Temporal SDK, which supports Ruby versions 3.2, 3.3, and 3.4.

Note:

  • Only macOS ARM/x64 and Linux ARM/x64 are supported.
  • Source gem is published but cannot be built directly.
  • Windows (MinGW) is not supported.
  • fibers/async are only supported on Ruby 3.3+.
  • See Platform Support for full details.

2. Start the Temporal Server Locally​

With the SDK installed, you’ll need a local Temporal Server to run your Workflows. The easiest way to do this is with Temporal CLI.

You can install the latest version with Homebrew using the following command:

brew install temporal

Once installed, run the development server by opening up a new terminal window:

temporal server start-dev

This will:

  • Start a Temporal Service on localhost:7233
  • Launch the Web UI on http://localhost:8233
  • Create the default namespace
  • Use an in-memory database (data is lost when you stop the server)

Leave this running in a separate terminal tab or window while you develop. You'll be able to monitor your Workflows through the Web UI as they execute.

Optional: To retain data between runs, use:

temporal server start-dev --db-filename my_temporal.db

3. Write Your First Activity and Workflow​

Now that you have the server running, it's time to create your first Temporal application. In Temporal, you'll create two files: an Activity file labeled say_hello_activity.rb and a Workflow file labeled say_hello_workflow.rb.

require 'temporalio/activity'

  class SayHelloActivity < Temporalio::Activity::Definition
    def execute(name)
      "Hello, #{name}!"
    end
  end
require 'temporalio/workflow'
require_relative 'say_hello_activity'

  class SayHelloWorkflow < Temporalio::Workflow::Definition
    def execute(name)
      Temporalio::Workflow.execute_activity(
        SayHelloActivity,
        name,
        schedule_to_close_timeout: 300
      )
    end
  end

A Temporal Workflow is your business logic, defined in code, outlining each step in your process. Activities are the individual units of work in your Workflow. Activities often involve interacting with the outside world, such as sending emails, making network requests, writing to a database, or calling an API, which are prone to failure. You can call Activities directly from your Workflow code. If an Activity fails, Temporal automatically retries it based on your configuration.

4. Run a Worker​

With your Activity and Workflow defined, you need a Worker to execute them. Create a file labeled worker.rb.
Workers, which are part of your application and provided by the Temporal SDK, then carry out the tasks defined in your Workflow.

require 'temporalio/client'
require 'temporalio/worker'
require_relative 'say_hello_activity'
require_relative 'say_hello_workflow'

client = Temporalio::Client.connect('localhost:7233', 'my-namespace')

worker = Temporalio::Worker.new(
  client:,
  task_queue: 'my-task-queue',
  workflows: [SayHelloWorkflow],
  activities: [SayHelloActivity]
)

worker.run(shutdown_signals: ['SIGINT'])

Workers are a crucial part of your Temporal application as they're what actually execute the tasks defined in your Workflows and Activities. For more information on Workers, see Understanding Temporal and a deep dive into Workers.

RUN THE WORKER

In a terminal window, start your Worker by running: ruby worker.rb

Keep this running in this terminal window. You should see output indicating that the Worker has started. Running this will run the Worker until Ctrl+C is pressed.

5. Execute a Workflow and See the Result​

With your Worker running, you can now trigger a Workflow Execution. This final step will validate that everything is working correctly with your file labeled execute_workflow.rb.

require 'temporalio/client'
require_relative 'say_hello_workflow'

client = Temporalio::Client.connect('localhost:7233', 'my-namespace')

result = client.execute_workflow(
  SayHelloWorkflow,
  'Temporal',
  id: 'my-workflow-id',
  task_queue: 'my-task-queue'
)

puts "Result: #{result}"

Expected output:

Result: Hello, Temporal!
EXECUTE WORKFLOW

To see the expected output, run this script in a new terminal window with the following command: ruby execute_workflow.rb

You've successfully executed your first Temporal Workflow. If you check the Temporal Web UI at http://localhost:8233, you'll gain visibility into your Workflow Execution with details listed about its progress and completion.

ADDITIONAL DETAILS ABOUT THE WORKFLOW EXECUTION
  • Temporal clients are not explicitly closed.
  • To enable TLS, the tls option can be set to true or a Temporalio::Client::Connection::TLSOptions instance.
  • Instead of start_workflow + result above, execute_workflow shortcut can be used if the handle is not needed.
  • Both start_workflow and execute_workflow accept either the workflow class or the string/symbol name of the workflow.
  • The handle above is a Temporalio::Client::WorkflowHandle which has several other operations that can be performed on a workflow. To get a handle to an existing workflow, use workflow_handle on the client.
  • Clients are thread safe and are fiber-compatible (but fiber compatibility only supported for Ruby 3.3+ at this time).

Next Steps​

Now that your local environment is set up, you're ready to explore more of what Temporal can do with the Ruby SDK.

  • Build More Workflows: Follow the Getting Started with Ruby tutorials to building and running your first Workflow step-by-step to see Temporal's full capabilities.
  • Understand the Core Concepts: Visit Understanding Temporal for a high-level overview of how Temporal works behind the scenes.
  • Learn by Example: Explore our Ruby code samples on GitHub for practical examples that demonstrate how to use the Temporal Ruby SDK.
  • Advance to Production-Ready: Check out the Core Application section of the Ruby Developer Guide to learn how to structure Temporal applications for real-world use.