Skip to main content


The Ruby interpreter is not embedded in Wasm Workers Server. To create workers based on this language, you first need to install a Ruby runtime.

Fortunately, we provide precompiled ruby.wasm modules in our WebAssembly Language Runtimes project, so the installation is simple:


To install the Ruby Wasm module, run the following command:

wws runtimes install ruby latest

Your first Ruby worker

Ruby workers are based on the Request / Response objects from the Web Fetch API. Since these entities don't exist in the Ruby language, the worker includes a polyfill with these two classes. You can find the polyfill code here.

In this example, the worker will get a request and print all the related information.

  1. First, create a new index.rb file with the following content. The worker method is mandatory as it will be the entrypoint for the worker:

    def worker(req)"Hello from Ruby in WebAssembly!")
  2. Now, you can add more content to the worker method to show the request information. In addition to that, let's add a response header.

    def worker(req)
    # Body response
    body = %{
    <!DOCTYPE html>
    <h1>Hello from Wasm Workers Server</h1>
    <p>Replying to #{req.url}</p>
    <p>Method: #{req.method}</p>
    <p>User Agent: #{req.headers["user-agent"]}</p
    <p>Payload: #{req.body || "-"}</p>
    This page was generated by a Ruby file inside WebAssembly

    # Build a new response
    res =

    # Add a new header
    res.headers["x-generated-by"] = "wasm-workers-server"

  3. Save the file

  4. If you didn't download the wws server yet, check our Getting Started guide.

  5. Install the Ruby runtime

  6. Run your worker with wws


    ⚙️ Loading routes from: .
    🗺 Detected routes:
    => index.rb (name: default)
    🚀 Start serving requests at
  7. Finally, open in your browser.

Add a Key / Value store

Wasm Workers allows you to add a Key / Value store to your workers. Read more information about this feature in the Key / Value store section.

To add a KV store to your worker, follow these steps:

  1. First, create a counter.rb file. It will access the KV store through the Cache object:

    CACHE_KEY = "counter";

    def worker(request)
    # Prepare the body
    count = Cache.get(CACHE_KEY).to_i || 0
    body = "The counter value is: #{count}"

    # Update the counter
    count += 1
    Cache.set(CACHE_KEY, count)

    # Return the response
  2. Create a counter.toml file with the following content. Note the name of the TOML file must match the name of the worker. In this case we have counter.rb and counter.toml in the same folder:

    name = "counter"
    version = "1"

    namespace = "counter"
  3. If you didn't download the wws server yet, check our Getting Started guide. You also need to install the Ruby runtime with the command below:

    wws runtimes install ruby latest
  4. Save the file and run your worker with wws:


    ⚙️ Loading routes from: .
    🗺 Detected routes:
    => counter.rb (name: default)
    🚀 Start serving requests at
  5. Finally, open in your browser.

Dynamic routes

You can define dynamic routes by adding route parameters to your worker files (like [id].rb). To read them in Ruby, access to the request.params object:

def worker(request)"The URL parameter is: #{request.params['id']}")

Read environment variables

Environment variables are configured via the related TOML configuration file. These variables are directly injected as global constants in your worker. To read them, just use the same name you configured in your TOML file:

name = "envs"
version = "1"

MESSAGE = "Hello 👋! This message comes from an environment variable"

Now, you can read the MESSAGE environment variable using the Ruby ENV class:

def worker(request)
"The environment variable value is: #{ENV.fetch('MESSAGE')}"

If you prefer, you can configure the environment variable value dynamically by following these instructions.