Skip to main content

Quick Start – Ruby SDK

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, start a local development server, and see a Workflow in action.

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.

Optional: To retain data between runs, use:

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

3. Write Your First Activity and Workflow​

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

4. Run a Worker​

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, which are part of your application and provided by the Temporal SDK, then carry out the tasks defined in your Workflow. For more information on Workers, see Understanding Temporal and a deep dive into Workers.

5. Execute a Workflow and See the Result​

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!

To follow more Ruby tutorials, visit learn.temporal.io/ruby.