Which is why, after more than a decade at 0.x, we were super excited to see SimpleCov ship its first stable release on July 12, 2026. In this article we’d like to share the details on the breaking changes, the deprecations and how to address them, if you’re impacted by them.

Everything below refers only to the 1.0.0 entry in the changelog.

Also, it’s worth noting that the minimum required Ruby version for this release is 3.2.

Breaking changes

How filters match paths

Two related changes can quietly alter which files end up in your report.

The first is that SourceFile#project_filename now returns a relative path, lib/foo.rb instead of /lib/foo.rb, which affects any anchored RegexFilter that relied on the leading slash. Because this breaks without a warning, you need to grep your codebase for patterns relying on the leading slash:

grep -rn "add_filter\|remove_filter\|add_group" .simplecov spec/spec_helper.rb test/test_helper.rb

Any pattern that anchors on a slash needs rewriting:

# Before
add_filter %r{^/lib/}

# After
add_filter %r{\Alib/}

The second change is that StringFilter now matches at path-segment boundaries, so "lib" matches /lib/ but no longer matches /library/. If you were deliberately relying on substring behavior, like saying add_filter "_spec" to catch user_spec.rb, switch that filter to a Regexp:

# Before: matched anything containing the substring
add_filter "generated"

# After: explicit substring matching
add_filter(/generated/)

This change has one very important observation to note, however: An argument containing a dot is still treated as a filename pattern and still matches as a substring, so add_filter "test.rb" continues to catch faked_test.rb. A trailing slash likewise still means directory-only matching. Only dot-free arguments like "lib" or "_spec" became segment-anchored.

The status line moved to stderr

The “Coverage report generated for X to Y” line, and the per-criterion totals under it, now go to stderr instead of stdout. If a CI script of yours parsed that line from stdout, it will now see nothing. You can suppress the message entirely on the formatter:

SimpleCov.formatter = SimpleCov::Formatter::HTMLFormatter.new(silent: true)

Or you can restore the old behavior at the call site:

bundle exec rspec 2>&1

HTMLFormatter now outputs coverage.json

SimpleCov used to automatically activate JSONFormatter when the CC_TEST_REPORTER_ID environment variable was set, and that special case is gone. It is no longer needed, because the default HTMLFormatter now writes coverage.json alongside the HTML report, serializing the same payload JSONFormatter would. If you relied on the old auto-activation and you weren’t using the HTML formatter, you’ll need to add either the JSONFormatter or the HTMLFormatter explicitly. Note that only one of them is needed and using HTMLFormatter gives you the JSONFormatter output plus the HTML report.

coverage.json schema change

coverage.json changed shape, from { "covered_percent": 80.0 } to the full { "covered": 8, "missed": 2, "total": 10, "percent": 80.0, "strength": 0.0 }, with covered_percent renamed to percent. On a related note, both simplecov_json_formatter and simplecov-html have been merged into the main gem. The old requires still work through a shim, so you can drop the separate gems from your Gemfile whenever it is convenient.

SimpleCov.start now loads the test_frameworks profile by default

Calling SimpleCov.start with no arguments now loads the test_frameworks profile by default, which filters out paths under test/, spec/, features/, and autotest/. Rails applications usually call SimpleCov.start "rails" instead, and the rails profile has loaded test_frameworks for as long as the profile has existed, so those projects need no change.

If you do call start with no arguments, your report will drop its overall coverage percentage, and how much depends on the ratio of test code to application code. Should you also set the minimum_coverage attribute and the new number fall below that threshold, you’ll need to either establish a new acceptable threshold or remove the filters:

# Option A: accept the more honest number and re-baseline the threshold
SimpleCov.minimum_coverage 80

# Option B: keep the old behavior by dropping the new filter
SimpleCov.start do
  remove_filter %r{\A(test|features|spec|autotest)/}
end

Option B is genuinely useful if you want to surface dead test helpers that nothing calls anymore. For everything else, re-baselining is the better move. If the number you land on is lower than you are comfortable with, we put together 10 strategies for upgrading apps with low test coverage that should help.

Parallel waits and two removals

Under parallel_tests, SimpleCov now waits in the first process rather than the last, using ParallelTests.first_process?, which matches what the parallel_tests README recommends. For most people this fixes a deadlock, and the old PARALLEL_TEST_GROUPS=1 workaround is no longer needed. The rare project that wired up its own wait_for_other_processes_to_finish in an after(:suite) hook keyed on last_process? now hits the symmetric deadlock and has to switch to first_process?.

Two removals round out this section. SimpleCov.coverage_criterion is gone and primary_coverage (or coverage :branch, primary: true) replaces it and the docile dependency is gone too, with SimpleCov.configure blocks now evaluated via instance_exec and instance variable proxying, which needs no action on your side unless you were doing something exotic inside a configure block.

Deprecations

Below we give a small description of the deprecations that were created in this version. While these don’t break now, we recommend effecting these changes so that future upgrades go smoothly.

The configuration API was redesigned

The config API has been reorganized around a smaller, more consistent set of verbs:

Most of these are a straight rename:

# Before
SimpleCov.start do
  add_filter "/vendor/"
  add_group "Services", "app/services"
  use_merging true
end

# After
SimpleCov.start do
  skip "/vendor/"
  group "Services", "app/services"
  merging true
end

The one to pay attention to is cover. It includes unloaded files the way track_files did, but it also restricts the report to the matching set given to it, so a single cover "lib/**/*.rb" will drop app/ from your report entirely. To keep the old behavior, pass every directory you want reported:

# Before
track_files "lib/**/*.rb"

# After: list everything, not just the previously-tracked glob
cover "lib/**/*.rb", "app/**/*.rb"

SimpleCov.start cannot be called from .simplecov

Calling SimpleCov.start from .simplecov is deprecated. Tracking still begins for backward compatibility, but you get a one-time warning, and a future release will require the explicit call to live in spec_helper.rb or test_helper.rb. Treat .simplecov as configuration only:

# .simplecov
SimpleCov.configure do
  skip "/spec/"
  minimum_coverage 90
end

# spec/spec_helper.rb, at the very top, before anything else is required
require "simplecov"
SimpleCov.start "rails"

:nocov: comments and associated configurations are deprecated

This means specifically the SimpleCov.nocov_token and SimpleCov.skip_token configurations. Every file still using # :nocov: emits a one-time warning to stderr at load time. Instances of # :nocov: must be replaced with the new directive comments, # simplecov:enable and # simplecov:disable:

# Before
# :nocov:
def hard_to_test
  legacy_thing
end
# :nocov:

# After
# simplecov:disable
def hard_to_test
  legacy_thing
end
# simplecov:enable

It’s worth mentioning that the directive comments also allow you to specify if you want to disable only line, branch or method coverage, like so: # simplecov:disable line. By default, all 3 are enabled.

branches_coverage_percent and methods_coverage_percent are deprecated

This will likely affect you only if you have custom formatters. SimpleCov::SourceFile#branches_coverage_percent and #methods_coverage_percent are now replaced by covered_percent which take a criterion argument that defaults to :line:

# Before
file.branches_coverage_percent
file.methods_coverage_percent

# After
file.covered_percent(:branch)
file.covered_percent(:method)

minimum_coverage_by_* setters deprecated

Finally, the minimum_coverage_by_file and minimum_coverage_by_group setters give way to the new coverage method’s minimum_per_file and minimum_per_group verbs:

# Before
SimpleCov.minimum_coverage_by_file line: 70, "app/x.rb" => 100

# After
SimpleCov.coverage(:line) do
  minimum_per_file 70
  minimum_per_file 100, only: "app/x.rb"
end

The no-arg getters are unchanged, and only the setter forms warn.

New features worth your time

Once you are migrated, there is a real payoff here.

Configuring criteria and scoping the report

The new criterion-first coverage method configures each criterion (:line, :branch, :method) in one place, with identical syntax regardless of which one you are configuring:

SimpleCov.start do
  coverage :line do
    minimum 90
    minimum_per_file 80
    maximum_drop 5
  end

  coverage :branch, minimum: 80, primary: true
end

The options are minimum, maximum, exact, maximum_drop, minimum_per_file (with only: overrides), and minimum_per_group.

Alongside it, SimpleCov.cover finally provides an allowlist. Where add_filter could only ever subtract, cover is the positive counterpart:

SimpleCov.start do
  cover "app/**/*.rb", "lib/**/*.rb"
end

It accepts string globs, Regexps, blocks, or arrays of those, and multiple calls union together.

Finally, if you want to start from a blank slate, SimpleCov.no_default_skips opts out of the filters SimpleCov.start installs.

Directive comments and synthetic branches

On the branch side, SimpleCov.ignore_branches lets you opt out of the synthetic :else branches that Ruby’s Coverage library reports for constructs with no literal else keyword, which includes exhaustive case/in matches, case/when without else, ||=, &&=, and if or unless without else:

SimpleCov.start do
  enable_coverage :branch
  ignore_branches :implicit_else
end

Rails applications get something else useful here: ignore_branches :eval_generated and the new ignore_methods :eval_generated drop the phantom branch and method entries that macros like delegate inject.

Parallel runners

SimpleCov’s coordination with parallel runners now goes through a pluggable SimpleCov::ParallelAdapters chain instead of hard-coding the parallel_tests gem’s API. Two adapters ship, one wrapping the parallel_tests gem and a generic one for any runner following the TEST_ENV_NUMBER and PARALLEL_TEST_GROUPS convention. Custom runners can register their own adapter by subclassing SimpleCov::ParallelAdapters::Base. There is also a new SimpleCov.parallel_wait_timeout (default 60 seconds) for the case where one worker runs much heavier files and routinely finishes well after the others, so raise it if you want that worker’s coverage in the merge rather than having the threshold checks run against a partial total.

Conclusion

There are other features we decided not to mention for brevity’s sake. They can all be found in the changelog, at any rate. Given what has changed, most migrations to SimpleCov 1.0 should be straightforward and we recommend to go through with it because the new features add many quality of life improvements for gathering good coverage reports especially in CI, which is essential for dealing with tech debt and guaranteeing your app is functioning as expected.

Here at FastRuby.io we use SimpleCov heavily and it’s one of the staple gems we always end up recommending to clients if they aren’t using anything.

If you want to also know what we can do for you and your team to make you move faster and not get dragged down by endless bugs, performance issues and legacy problems no one understands anymore, send us a message and let’s talk!.

Resources and Further Reading

• SimpleCov 1.0.0 changelog
• SimpleCov README
• Ruby’s Coverage library

Not all code belongs on RubyGems.org, and that’s okay. Sometimes the goal is internal reuse- sharing an SDK or auth client across services. Sometimes it’s a business model: you ship a private gem behind a license. Either way, the constraints are the same: authentication, delivery, and trust.

In this blog post, we’ll give an overview of the options for distributing private gems.

How Private Gems Are Born

Organizations use private gems for practical reasons. Gems that are built for internal usage can be seen as a convenient way to share libraries such as SDKs, service clients, and shared models across many services without coupling through a monorepo. Organizations can also have advanced functionality as closed source gems and sell access to it.

These use cases share common operational challenges: you must authenticate and authorize installs, deliver updates and prevent unauthorized redistribution. Addressing those concerns influences the distribution method you pick and the infrastructure you operate.

How RubyGems and Bundler Handle Sources

By default gem push targets RubyGems.org and Bundler resolves dependencies from the sources declared in your Gemfile. For example:

source "https://rubygems.org"

gem "rails", "~> 7.1"

However, both behaviors are configurable. gem push accepts a --host flag so you can upload to another gem server, and the RubyGems client will also read credentials from ~/.gem/credentials or the GEM_HOST_API_KEY environment variable. Meanwhile, Bundler reads sources from the Gemfile, but you can store credentials with bundle config (which writes to .bundle/config), configure mirrors, or point specific hosts to private registries.

Behind the scenes bundle install downloads metadata from the configured registry, verifies checksums, and installs gems locally. Because RubyGems.org lacks private access controls and payment hooks, organizations that aim to distribute their private gems usually use a private registry or use private Git repos as an alternative.

Private Gem Distribution

Git-Based Distribution

It’s the simplest option to distribute a private gem. Publish the gem source to a private repository and reference it in your Gemfile. This leverages existing Git authentication (SSH keys or OAuth) and avoids running a registry. For small teams or internal tooling this is often the path.

Referencing a Git repo moves work to the client. Bundler cannot use a pre-built index, so installs can be slower and metadata caching is limited. Because Bundler doesn’t have an index for Git sources, automating version access or licensing controls (for example, restricting which versions a particular customer can install) becomes harder to manage at scale.

gem "my_private_gem", git: "git@github.com:org/my_private_gem.git"
# or with specific branch/tag
gem "my_private_gem", git: "https://github.com/org/my_private_gem.git", branch: "main"
# or with specific ref
gem "my_private_gem", git: "git@github.com:org/my_private_gem.git", ref: "v1.2.3"

Private Gem Servers

Private gem servers, whether managed SaaS or self-hosted, address the shortcomings of Git-based installs by providing an indexable registry with access control, logging, and lifecycle management. Example commercial providers include Gemfury and Cloudsmith; larger organizations often choose Artifactory.

If you prefer an open-source server, two lightweight and commonly used options are Gemstash and Geminabox.

Gemstash (lightweight, RubyGems-friendly)

Gemstash is a small server that can host private gems, proxy and cache RubyGems.org, and provide simple authentication. It’s maintained by contributors in the RubyGems ecosystem and is opinionated for standard Bundler/Rubygems workflows.

Here’s a quick start to run a local server:

# install and run a local server
gem install gemstash
gemstash start   # serves at http://localhost:9292 by default

# build and push a gem
gem build mygem
gem push --host http://localhost:9292 pkg/mygem-0.1.0.gem

# point your Gemfile at the server
source 'http://localhost:9292'

It’s also possible to set up authentication and tokens in this Gemstash local server. Check their documentation for more information.

Geminabox (simple, small footprint)

Geminabox is Sinatra app that serves gems from a directory. It’s extremely lightweight and easy to deploy (single process), making it a good choice for small teams or quick internal registries.

Here’s a quick start to run a local server:

# install and run the server
gem install geminabox
geminabox   # runs a server (defaults to http://localhost:9292)

# build and push a gem (uses 'gem inabox' which is provided by the geminabox toolchain)
gem build mygem
gem inabox pkg/mygem-0.1.0.gem --host http://localhost:9292

# point your Gemfile at the server
source 'http://localhost:9292'

For production use, Geminabox or Gemstash can be set up behind an authenticated reverse proxy strategy (Nginx with basic auth or an SSO gateway) or use TLS + token-based access. Both servers are widely used, well-documented, and simple to operate.

Bundler can be pointed at a private source using an authenticated URL, for example:

source "https://USERNAME:TOKEN@gem.fury.io/myorg/"

Tokens or API keys are typically injected through environment variables or stored in Bundler’s local config (.bundle/config). Running a registry gives you practical operational controls: you can revoke access, audit downloads, and integrate the registry with CI/CD for automated publishing.

Private Gem Registries

When productizing a gem, distribution and authentication become core product components. Projects like Sidekiq provide license keys that act as credentials against a private registry; others (for example, providers of long-term support) gate patches and releases behind subscription checks. The implementation is typically the same: a license service issues short-lived or revocable tokens, a registry enforces access, and CI/CD pipelines publish releases and reconcile entitlement after successful payments.

Fundamentally, a commercial private gem system typically rests on three pillars:

• Entitlement Management: A service (like a license server) that knows who is allowed to access what.
• Enforcement Point: A private registry that checks these entitlements before serving gems.
• Automation Bridge: Pipelines that automatically grant or revoke access based on events like payment or subscription changes.

It also should account for other security controls like: rotating tokens, scoped credentials, and signing artifacts to reduce risks.

Security and DevOps Considerations

Shipping a private gem rests on a practical security responsibility: controlling who can fetch your packages.

Implement least-privilege tokens (separate tokens for publishing vs. install), integrate with SSO where possible, and have a token rotation and revocation process for offboarding or compromised keys.

Real-World Examples

Sidekiq Pro

• Uses token-based authentication for Bundler installs.
• Paid customers receive personal tokens tied to their license.
• Gems are hosted on a private server with strict version control.

Rails LTS

• Customers manually configure credentials after purchasing.
• Patches are distributed as gem updates to specific Rails versions.
• Focuses on compliance and security rather than automation.

Internal Gems (Enterprise Use)

• Common in microservice organizations.
• Teams use self-hosted Gemstash for internal SDKs.
• Easy integration with GitHub Actions or CircleCI.

Conclusion

Private gems effectively bridge the gap between open-source collaboration and commercial or internal sustainability. By choosing the right distribution method, from a simple Git repo to a fully-featured private registry, and adhering to sound security principles, you can share your gem safely. Whether you’re building a shared internal SDK or selling a pro-tier library, the goal remains the same: secure your pipeline, manage trust, and respect your users’ access.

Need help setting up secure private gem distribution for your team? We can help.

What is a Multi-Stage Dockerfile?

You might have a Dockerfile in your application that looks something like this:

FROM ruby:3.2

WORKDIR /app

# Install system dependencies needed to compile native gems
RUN apt-get update && apt-get install -y \
    gcc \
    make \
    libpq-dev

# Install gems
COPY Gemfile Gemfile.lock ./
RUN bundle install

# Copy application code
COPY . .

EXPOSE 3000
CMD ["ruby", "app.rb"]

This is a typical single-stage setup. There’s one base image, for example, ruby:3.2, and everything your application needs gets installed inside it: the full Bundler toolchain, build utilities like gcc and make for compiling native gem extensions, and dev dependencies like RSpec or Pry, all living side by side. The appeal is obvious. It’s straightforward to write, easy to reason about, and gets the job done.

But that simplicity comes with a trade-off. For example, every tool you used to build your application is still sitting inside the image you ship to production even though you no longer need it there.

In contrast, a multi-stage Dockerfile introduces the idea of stages, discrete phases of your build process, each defined by its own FROM statement. Here’s what that looks like in practice:

• Multiple FROM statements: each one starts a new stage with its own base image and its own filesystem. You might have a builder stage that installs compilers and build tools, and a separate production stage that only contains what your application needs to run.
• Selective artifact copying stages can pull specific files from a previous stage using COPY --from=<stage>. This means your final image gets only the output of the build such as compiled code and static assets, and not the tools that produced it.

Here’s an example of what a multi-stage Dockerfile looks like in practice. This multi-stage Dockerfile is from the most recent version of Rails:

# syntax=docker/dockerfile:1
# check=error=true

# This Dockerfile is designed for production, not development. Use with Kamal or build'n'run by hand:
# docker build -t rails_demo .
# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name rails_demo rails_demo

# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html

# Make sure RUBY_VERSION matches the Ruby version in .ruby-version
ARG RUBY_VERSION=4.0.4
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base

# Rails app lives here
WORKDIR /rails

# Install base packages
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y curl libjemalloc2 libvips sqlite3 && \
    ln -s /usr/lib/$(uname -m)-linux-gnu/libjemalloc.so.2 /usr/local/lib/libjemalloc.so && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Set production environment variables and enable jemalloc for reduced memory usage and latency.
ENV RAILS_ENV="production" \
    BUNDLE_DEPLOYMENT="1" \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT="development" \
    LD_PRELOAD="/usr/local/lib/libjemalloc.so"

# Throw-away build stage to reduce size of final image
FROM base AS build

# Install packages needed to build gems
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential git libvips libyaml-dev pkg-config && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Install application gems
COPY vendor/* ./vendor/
COPY Gemfile Gemfile.lock ./

RUN bundle install && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \
    # -j 1 disable parallel compilation to avoid a QEMU bug: https://github.com/rails/bootsnap/issues/495
    bundle exec bootsnap precompile -j 1 --gemfile

# Copy application code
COPY . .

# Precompile bootsnap code for faster boot times.
# -j 1 disable parallel compilation to avoid a QEMU bug: https://github.com/rails/bootsnap/issues/495
RUN bundle exec bootsnap precompile -j 1 app/ lib/

# Precompiling assets for production without requiring secret RAILS_MASTER_KEY
RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile

# Final stage for app image
FROM base

# Run and own only the runtime files as a non-root user for security
RUN groupadd --system --gid 1000 rails && \
    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash
USER 1000:1000

# Copy built artifacts: gems, application
COPY --chown=rails:rails --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --chown=rails:rails --from=build /rails /rails

# Entrypoint prepares the database.
ENTRYPOINT ["/rails/bin/docker-entrypoint"]

# Start server via Thruster by default, this can be overwritten at runtime
EXPOSE 80
CMD ["./bin/thrust", "./bin/rails", "server"]

Here’s what’s happening across the three stages:

• base: this stage sets up the common foundation (slim Ruby image, shared env vars) that both other stages build on.
• build: the throw-away stage. Installs build-essential, git, compiles gems, precompiles assets. None of these tools ship to production.
• the unnamed third FROM base: this copies only the built artifacts from build and runs as a non-root user.

Why Use a Multi-Stage Dockerfile?

Now that we know what the differences are between a single-stage and multi-stage Dockerfile, let’s talk about why you might choose a multi-stage Dockerfile.

Two main advantages of multi-stage builds are performance and security:

Performance

Multi-stage builds usually have a smaller final image size since the build tools and dev dependencies don’t make it into the final image. Multi-stage builds also play nicely with Docker’s layer caching. Because each stage is isolated, Docker can cache them independently. If your dependencies haven’t changed, the builder stage can be skipped entirely on the next run. You only rebuild the stages that actually changed, which adds up to significant time savings over hundreds of pipeline runs. Smaller images and cached stages mean faster pulls, faster deployments, and less time waiting around in your CI/CD pipeline.

Security

A multi-stage build is more secure than a single-stage build because the production image contains only what’s needed to run the application, nothing more.

Every package installed in your image is a potential vulnerability. Build tools like gcc, make, and curl are common in single-stage images and they’re also common exploit vectors. With a multi-stage build, those tools never make it into your production image. Fewer packages means fewer CVEs to worry about, and a much smaller surface for attackers to target.

You can reduce this even further by pairing your final stage with a slim base image. For example, ruby:4.0-slim strips out packages that aren’t needed for most Ruby apps, and ruby:4.0-alpine goes even further, using Alpine Linux as its base, a minimal OS that keeps only the bare essentials by default.

Tips and Common Pitfalls

• Skip multi-stage for development and test environments. The security and build-performance wins mostly matter for what you ship to production. In dev you’re rebuilding constantly and want to run commands like bundle install, rails console, or add a gem on the fly. A multi-stage setup adds friction for little payoff there, since your dev tools need to stay in the image anyway. Keep a single-stage Dockerfile (or a dedicated dev stage in the same file) for local development and testing, and reserve the multi-stage build for your production image.
• Name your stages. Using AS builder and AS production in your FROM statements makes your Dockerfile much easier to read and maintain, especially as the number of stages grows.
• Know what to copy. The most common stumbling block is figuring out exactly which files need to move between stages. For a Ruby app, that’s typically your installed gems directory and your application code. Take the time to map this out before you write the COPY --from lines.
• Run as a non-root user in your final stage, like the Rails example above does. Even if an attacker gets into the container, they won’t have root access to work with.
• Build cache ordering matters: Put the steps least likely to change at the top of each stage and most likely to change at the bottom. For example, copy your Gemfile and run bundle install before copying your application code. That way, if you change a Ruby file, Docker doesn’t re-run bundle install unnecessarily.
• Match your base images when going slim or Alpine. If your final stage switches to a musl-based image like ruby:4.0-alpine, but your builder stage compiled native gem extensions on a glibc-based image like ruby:4.0 or ruby:4.0-slim, those extensions may fail at runtime. Either build and run on matching bases, or compile your gems inside an Alpine builder stage.
• Forgetting build dependencies at runtime. A very common mistake is copying your compiled gems into the final stage but forgetting to install the runtime system libraries they depend on. For example, the pg gem needs libpq5 at runtime even though it only needs libpq-dev to compile. Your app will build fine but crash at runtime. This is probably the most common real-world gotcha with multi-stage builds.
• Secret leakage between stages. People sometimes assume that because secrets (API keys, credentials) used in the build stage don’t get copied to the final stage, they’re safe. But they can still be exposed in the image’s layer history. Use Docker BuildKit secrets instead:

  RUN --mount=type=secret,id=my_secret ...
  

• If you want to go even further than slim images, look into distroless images. These images contain absolutely nothing except your app and its runtime- no shell, no package manager, nothing. They represent the ultimate reduction in attack surface. Just be aware that Ruby support for distroless is still limited compared to languages like Go or Java, so do your research before committing to it for a Ruby project.

Conclusion

Multi-stage Dockerfiles require slightly more work upfront. But in return, you get images that are dramatically smaller, meaningfully more secure, and faster to build. That’s a trade-off worth making for any production workload.

Want to convert your single-stage Dockerfiles to multi-stage? We can help!

Most of the time, what we have seen is that the Ruby code executed when running these tools ends up left behind and not being counted for the total code coverage, even though we know the code is actually being tested.

Sample Application

To make it easier to try this, we created a sample application that uses the cypress-on-rails gem along with Minitest, and includes the instructions and custom Rake tasks to get the final code coverage when running both test suites.

Note that this could be done with any other tool like Playwright or Protractor (deprecated) since the actual integration is independent of the tool as long as it runs the Rails server.

Approach Summary

The main problem that we are facing when using these external tools is that the Rails server is controlled by this runner and not started by a Ruby runner, so we can’t easily control the lifecycle of the server to measure and extract the coverage information.

We can see how the cypress-on-rails gem already overcomes some of these limitations with custom helpers to execute fixtures, factories, and db cleanup in their generated sample tests.

We have a few moving pieces here, so this is a quick summary of the process:

• when we run rails test we get the code coverage of the Minitest test suite
• then we’ll run Coverband’s standalone server on the side, so it collects stats from the Rails servers started by Cypress
• once the e2e tests are done (running rails cypress:run), we can use a custom Rake task to extract the code coverage from Coverband into a JSON file
• finally, we can merge the code coverage of the 2 tools into a single final report

The Details

Minitest Code Coverage

This step is the standard SimpleCov setup: we only need to add the SimpleCov gem in the :test group, and enable SimpleCov at the beginning of our test_helper.rb file.

After this we can do a quick test, run rails test and see the generated report:

We can see the total coverage is around 35%, and we can see the details of the UsersController coverage that we’ll use for this example too:

Note the total coverage of this file is around 39%, with many lines not covered (lines 15, 24, and 26). This is expected, as we are only testing the index action in our Minitest suite.

But we know we have more tests for this file; the Cypress test suite is testing an invalid form submission of the new user form.

Coverband Standalone Server

As mentioned above, we can’t simply add SimpleCov to the Cypress tests, so we are going to use Coverband (which uses SimpleCov internally) to capture the code that is being executed by the tests, similar to what we would do if running Coverband in production.

Coverband provides a standalone server that we can use so we can control the lifecycle of the code coverage tracking independently of the lifecycle of the Cypress runner.

First we have to add the coverband gem (note that we are adding it only in the test group, we are not using it to track production coverage!). Then, we can execute the server with RAILS_ENV=test rails coverband:coverage_server and leave it running on the side.

Note that, now that Coverband is added, we get an error message at the end of the Minitest run. Ideally, we could use a different Rails environment for the e2e tests so the gem wouldn’t be loaded, but the cypress-on-rails gem hardcodes the test Rails environment.

E, [2026-01-02T16:29:34.221521 #322239] ERROR -- : coverage failed to store
E, [2026-01-02T16:29:34.221579 #322239] ERROR -- : Coverband Error: #<RuntimeError: coverage measurement is not enabled> coverage measurement is not enabled

Running Cypress Tests

Now it’s time to run the e2e tests. In this example we run rails cypress:run, but it would be the same for any other tool, as long as we set the same RAILS_ENV variable as the Coverband server (so the gem is required).

When the tests finish, we won’t see any information about the code coverage, but we can open the Coverband server in the browser to check how the percentage is being tracked in http://localhost:9022.

It’s important to note that Coverband will calculate all the coverage of any code that gets executed (even for Ruby files we don’t really care about when looking at the final code coverage value) and we get some information like coverage of config files or test files that will affect the coverage percentage. With SimpleCov, we use the 'rails' profile to ignore those extra files, but we don’t need to worry about it at this point for Coverband. We’ll clean that up at the end.

Extracting the Code Coverage from Coverband

Coverband provides a coverband:coverage_html task that uses SimpleCov to process the internal coverage data. There’s also a coverband:coverage_json but these tasks don’t generate the raw data we need to merge it with the Minitest resultset. To solve this, we created a custom Rake task that will extract the raw data and format the JSON file to have a structure that we can then merge.

# https://github.com/fastruby/coverage-with-cypress-sample-app/blob/main/lib/tasks/json_coverage.rake#L2

desc "JSON formatted report of Coverband code coverage"
task :simplecov_json_report do
  require "coverband"
  require "coverband/utils/result"
  require "coverband/utils/file_list"
  require "coverband/utils/source_file"
  require "coverband/utils/lines_classifier"
  require "coverband/utils/results"

  require "simplecov"
  require "simplecov_json_formatter"

  `mkdir -p #{SimpleCov.coverage_path}`

  # SimpleCov hardcodes this constant as `coverage.json`, we are renaming this here to make it more
  # clear, but this step is not necessary
  SimpleCovJSONFormatter::ResultExporter.send(:remove_const, "FILENAME")
  SimpleCovJSONFormatter::ResultExporter::FILENAME = "cypress_coverage.json"

  coverband_reports = Coverband::Reporters::Base.report(Coverband.configuration.store)
  Coverband::Reporters::Base.fix_reports(coverband_reports)
  result = Coverband::Utils::Results.new(coverband_reports)
  SimpleCov::Formatter::JSONFormatter.new.format(result)

  # fix json structure so it can be merged with coverage:merge
  # we want a `"Cypress"` key at the root of the JSON object, with the `"coverage"` inside it
  generated_json_file = File.join(SimpleCov.coverage_path, SimpleCovJSONFormatter::ResultExporter::FILENAME)
  content = { "Cypress" => JSON.parse(File.read(generated_json_file)) }
  File.write(generated_json_file, content.to_json)
end

Now we can run rails simplecov_json_report to generate the coverage/cypress_coverage.json file.

Note that this step will show a really high code coverage percentage, over 75%, but this is not correct since it includes config, test, and other files for this calculation!

Merging Results

Now we get to the final step: we have the coverage/.resultset.json and coverage/cypress_coverage.json files that we need to merge into a single file.

For this, we have created another custom Rake task that uses SimpleCov’s collate method:

# https://github.com/fastruby/coverage-with-cypress-sample-app/blob/main/lib/tasks/json_coverage.rake#L34

namespace :coverage do
  desc "Merge Minitest's and Cypress' code coverage json files into one"
  task :merge do
    require "simplecov"

    # change this if you use different json result names
    coverage_files = Dir["#{SimpleCov.coverage_path}/.resultset.json"] + Dir["#{SimpleCov.coverage_path}/cypress_coverage.json"]

    # make sure to use the `rails` profile to not add noise with files we won't test
    SimpleCov.collate coverage_files, "rails"
  end
end

And we can run this task with rails coverage:merge and see the new generated code coverage report:

Here we can see the total percentage went up to almost 53%.

And here we can see the UsersController coverage is over 60% and we can see the lines inside the new and create actions are now green as we expected from the Cypress test.

Conclusion

This is a basic example of the approach; in a real production application it may require some tweaks depending on the tool being used, along with the proper setup for CI and proper automation of the extraction and merging of the coverage data.

A similar problem happens when we want to measure the JavaScript/TypeScript code coverage and we are using a Ruby runner like Capybara along with runners like Jest or Cypress. You can read about capturing all the code coverage and merge results together in this article: JavaScript Test Code Coverage in Rails.

Do you need help with your tests? Let’s talk!

That rule quietly stopped being enough. AI coding editors like Claude Code and Cursor read project-local configuration the moment you open a repository, and some of that configuration is executable. A repo you cloned five seconds ago can hand your editor a command to run before you have read a line of it, and this is not hypothetical: the npm worm that hit keyv this week (Socket, Aikido, and Microsoft all covered it) weaponized exactly this, writing itself into .claude/settings.json so it runs again for anyone who opens the project.

In this post, we’ll look at why opening a repository in an AI editor is now an execution event, how the keyv worm turned that into a live attack, and what to check in a cloned repo’s .claude/ and .vscode/ directories before you point your editor at it.

Why opening a repo now executes code

For years the mental model was simple: untrusted code runs when you tell it to. You install a package and its install scripts run, you run the app and its code runs, but opening a repository to read it was passive. Looking wasn’t doing.

AI editors break that model by design. Claude Code reads .claude/settings.json on every session start, and one of the things that file can configure is a SessionStart hook, a shell command that runs when the session begins, with no separate step asking you to approve it first. A .claude/ directory you didn’t create can hand your session a command just as easily as one you built yourself.

Cursor and VS Code have the same shape with more friction: a task in .vscode/tasks.json can be set to run on folder open, though only in a workspace you have trusted and only once you have opted into automatic tasks. Either way, the config is meant to be read and acted on the moment the project opens, which is exactly what makes it useful to someone who has slipped it into a repo you are about to clone.

A configuration-injection bug in marimo, a Python notebook tool (CVE-2026-67618), surfaced the same week and leaked API keys the moment you opened a crafted notebook, a different mechanism with the same shape. Two unrelated tools hitting the same problem in the same week is a sign this is a shift in how tools treat project-local config, not an npm or a Rails quirk. The common thread is that the more a tool reads and acts on configuration shipped inside a project, the more of its behavior a repo you didn’t write controls the moment you open it.

Already weaponized: the keyv worm

The keyv worm shows this is not a theoretical risk. The npm package keyv, along with a few hundred others, was compromised on August 4th, 2026, in a self-propagating worm variously called ChainDrop or “Shai-Hulud: Here We Go Again”. The credential-stealing half of it is ordinary: an install script harvests tokens and keys from the filesystem and ships them out to the attacker. The half that matters here is how it sticks around. As Socket noted, listing it among techniques “not documented in earlier Shai-Hulud reporting,” the payload writes a SessionStart hook into .claude/settings.json and a folderOpen task into .vscode/tasks.json.

Those files are never touched by npm install. The next time you or a teammate opens the project, they are read by your editor, which means the infection outlives the dependency. You can pull the compromised package out of your lockfile and the hook waiting in .claude/ is still there, ready to run the next time someone opens the repo in Claude Code. That is the difference between “we shipped a bad dependency” and “everyone who opens this repo runs the payload,” and it is why cleaning up after this worm is not just a lockfile edit.

Why your usual instincts miss it

None of the usual reflexes catch this. “Don’t run code you haven’t read” and “only install signed, attested packages” are both good habits, and both miss the point here, because the dangerous part isn’t something you run or install at all. The hook rides in the repository’s own files. Provenance, a signed record tying a package back to the exact source commit and CI build that produced it, tells you which pipeline published a dependency; it says nothing about a .claude/settings.json committed straight into a repo you cloned. Ruby has its own take on verifying the packages you install, the gem signing and --trust-policy we looked at in The Forgotten Flag: How –trust-policy Works, and it shares the same blind spot: signing covers the artifacts you install, not the config you open.

Why this lands on Rails teams

This started as an npm story, but the exposure isn’t really about your dependencies. If your Rails app has a Node asset pipeline it is worth keeping an eye on your lockfile, and keeping Gemfile.lock honest matters too (we have written before about supply-chain risk in your Gemfile and about how patching a gem isn’t always the whole fix). But a gem or npm dependency audit looks at what you install. The .claude/ and .vscode/ vector is about what you open, and opening repositories you didn’t write is something Rails teams do constantly.

Consultancies live this at the extreme: at FastRuby.io we open other people’s Rails codebases for a living, cloning client applications to audit and upgrade them, more often than not with an AI editor already running. Every one of those repositories is, by definition, one we did not write, and any of them could ship a .claude/settings.json that runs the moment the session starts. A dependency audit answers “did I install something bad?” but it has nothing to say about the question that actually applies here: whose repo did I just open in Claude Code?

What to check before you open a repo

So before you open a freshly cloned repository in Claude Code, Cursor, or VS Code, especially one from outside your team, spend a minute on the config it ships with (the kind of check worth eventually baking into a Claude Code skill so you are not relying on memory):

• Open .claude/settings.json and look for a hooks key, particularly a SessionStart hook. A legitimate hook is one your own team added on purpose; anything you don’t recognize is worth reading in full, because it runs on session start whether or not you asked.
• Open .vscode/tasks.json and look for a task set to run on folder open, and read exactly what its command does.
• If the repo has a JavaScript pipeline, check whether your lockfile resolves keyv, flat-cache, file-entry-cache, or cacheable to one of the poisoned releases (keyv@6.0.0, flat-cache@6.1.24, file-entry-cache@11.1.6, cacheable@2.5.1) rather than to the older, clean lines. yarn why keyv or npm ls keyv shows what actually resolved.

If any of that turns up something you didn’t put there, deleting the file isn’t the end of it. Assume the command already ran, and rotate every credential the machine or CI run could have reached since you opened the repo, from a separate, uncompromised machine. A hook you remove after the fact doesn’t recall whatever it already sent out.

Conclusion

Opening a repository in your editor used to be the safe step, the thing you did precisely because you weren’t ready to run anything yet. AI editors changed that: Claude Code and Cursor read project-local config on open and can act on it, so cloning a repo you didn’t write and pointing an AI editor at it is an execution event in its own right. The keyv worm is the first widely seen case of someone weaponizing that, and it will not be the last.

For Rails teams, and especially for anyone who clones client code for a living, the habit worth building is a small one: before you open an unfamiliar repo in an AI editor, look at its .claude/ and .vscode/ directories the same way you would look at a shell script someone emailed you. A few minutes there is a lot cheaper than rotating every credential on the box afterward.

Wondering what is hiding in the .claude/ or .vscode/ config of the repos your team has been cloning, or want a second set of eyes on a codebase before you trust it? Send us a message!

cssbundling-rails: Command install failed, ensure bun is installed
Tasks: TOP => assets:precompile => css:build => css:install

Except your application uses Yarn. It has always used Yarn. Nothing in the project references Bun, and nobody on the team added it.

This is not an exotic edge case. It can happen to ordinary Yarn applications, and it lingers because the fix has been merged upstream but never released. In this post, we’ll walk through why cssbundling-rails misidentifies your package manager, and how to unblock your build.

The Short Version

cssbundling-rails 1.4.3 added yarn.lock to the list of lockfiles that mark a project as a Bun project. While preparing to install JavaScript dependencies, cssbundling-rails determines that Bun should be used when the Bun binary exists in the PATH. The issue explored in this post occurs when two things are true at once: the project contains a yarn.lock file and the build environment happens to have Bun installed.

When both are true, the gem runs bun install against a project that has never used Bun. If that command fails, the rake task reports ensure bun is installed even though Bun is installed, because the message is assembled from the name of the command it just tried to run.

The fix is PR #172, commit 466cd57, merged to main in July 2025. As of August 2026 it is still not in a released version, and 1.4.3 remains the latest gem. So the workaround is to pin to the commit rather than to a version:

gem "cssbundling-rails", github: "rails/cssbundling-rails", ref: "466cd57"

You are likely to hit this if all of the following are true:

• You use cssbundling-rails with Yarn, and yarn.lock is committed.
• Your resolved version is 1.4.3. It is currently the latest release, so bundle update lands you there by default.
• Bun is reachable on PATH wherever you run assets:precompile, whether that is a Docker build, CI, or a PaaS build step. This is easier to hit than it sounds: Render’s images ship Bun by default, plenty of custom base images install it alongside Node, and so does any developer who has ever tried Bun locally.

Note that your project does not need to use Bun in any way, and you do not need both a yarn.lock and a bun.lock. An ordinary Yarn application is enough, as long as the Bun binary happens to be sitting in the environment that runs the build.

How We Ran Into It

We hit this while moving a Rails application onto a newer Ruby base image. It had used Yarn for years. Bun had never entered the picture.

Everything built cleanly until assets:precompile, which stopped on ensure bun is installed. Our first assumption was that some dependency had quietly started pulling Bun in, so we went looking through package.json and the lockfile. Neither pointed to Bun. The gem had not failed to run a command; it had decided on its own to run the wrong one.

The answer was in a shared base image. A little above the Ruby setup, it installed Bun, so it would be available to other projects using it, and put it on the path:

RUN curl -fsSL https://bun.com/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

Our project did not need Bun, but every build now ran with Bun in PATH. Those two lines (above) are what turned a quirk in a gem’s detection logic into a failed build.

That reframed the investigation. The question was not “why is Bun broken”, it was “why is a Yarn application attempting to use Bun?”

What’s Actually Happening

The task graph in the error message is the first clue:

assets:precompile => css:build => css:install

cssbundling-rails hooks into assets:precompile and runs css:build, which depends on css:install, which shells out to a package manager to install your JavaScript dependencies. The gem picks that package manager automatically, based on which lockfiles it finds in the project.

For the precompile path, that decision lives in Cssbundling::Tasks, in lib/tasks/cssbundling/build.rake. The relevant parts of version 1.4.3 looks like this:

LOCK_FILES = {
  bun: %w[bun.lockb bun.lock yarn.lock],
  yarn: %w[yarn.lock],
  pnpm: %w[pnpm-lock.yaml],
  npm: %w[package-lock.json]
}

def install_command
  case
  when using_tool?(:bun) then "bun install"
  when using_tool?(:yarn) then "yarn install"
  when using_tool?(:pnpm) then "pnpm install"
  when using_tool?(:npm) then "npm install"
  else raise "cssbundling-rails: No suitable tool found for installing JavaScript dependencies"
  end
end

def tool_exists?(tool)
  system "command -v #{tool} > /dev/null"
end

def using_tool?(tool)
  tool_exists?(tool) && LOCK_FILES[tool].any? { |file| File.exist?(file) }
end

Two details: yarn.lock sits in the Bun list, so every Yarn project matches the Bun branch. And using_tool? joins both checks with &&, so the Bun match only wins when tool_exists? actually finds the bun binary. With Bun absent, the check falls through to Yarn and everything works, which is why this bug stays invisible on a plain ruby:* image. With Bun present, install_command returns bun install for a project that has never used Bun.

From there the misclassification lands in one of two ways. If bun install succeeds, it quietly writes a bun.lock into the repository alongside your yarn.lock, which is what most of the upstream reports describe. If it fails, the css:install task raises:

task :install do
  command = Cssbundling::Tasks.install_command
  unless system(command)
    raise "cssbundling-rails: Command install failed, ensure #{command.split.first} is installed"
  end
end

That is the message we saw, and it is built from command.split.first. It points you at Bun as the problem, when Bun was never part of the application to begin with.

Where the Regression Came From

The git history explains how a change meant to help Bun users introduced a bug that impacted Yarn users.

PR #165, “Improve package manager detection for Bun 1.2 compatibility”, was merged in March 2025 and shipped in 1.4.3. Bun 1.2 made a new text-based bun.lock the default lockfile in place of the older binary bun.lockb, and bun install --yarn produces a yarn.lock. To cover those cases, the PR broadened Bun detection to accept bun.lockb, bun.lock, or yarn.lock.

That last option is the problem. Every Yarn project has a yarn.lock, so detection meant for a narrow Bun workflow started capturing ordinary Yarn projects too, on any machine where Bun was installed.

PR #172, “Remove yarn from bun detect tool”, commit 466cd57, was merged in July 2025 to correct it. It stops treating yarn.lock as a Bun signal, so a Yarn project is detected as Yarn again.

It is worth knowing that this was not a simple typo. Issue #183 is still open and asks for the opposite behavior: Bun preferred for freshly generated applications. The same few lines are being pulled in two directions, and there is no clear consensus upstream on how it should behave.

Merged Is Not Yet Released

Unfortunately the usual “just bump the version” instinct does not work in this case. The latest released gem is 1.4.3, tagged March 3, 2025. The fix, 466cd57, was merged to main on July 10, 2025, but not yet released. The only way to get the fix today is to point Bundler at the commit itself:

# cssbundling-rails 1.4.3 misdetects bun for yarn projects (regression from
# PR #165). The fix is PR #172 / 466cd57, merged to main but unreleased as of
# August 2026. Unpin only once a release LATER than 1.4.3 ships with that commit.
gem "cssbundling-rails", github: "rails/cssbundling-rails", ref: "466cd57"

As a side note, when you pin a gem to a commit, it is a good idea to add a comment that describes the condition that makes it safe to remove. In this case, once a release later than 1.4.3 ships with commit 466cd57. A comment like ‘unpin after v1.4.3’ is easy to misread and does not explain why the dependency was pinned in the first place.

Now we can bundle install, and confirm that the Gemfile.lock records a GIT source pointing at the commit:

GIT
  remote: https://github.com/rails/cssbundling-rails.git
  revision: 466cd57...
  specs:
    cssbundling-rails (1.4.3)

Rebuild, and precompilation detects Yarn again. That one-line pin unblocked the applications that still needed a CSS build.

Conclusion

The alarming ensure bun is installed message is not about Bun at all, it is an ordinary Yarn application tripping over a detection change in cssbundling-rails 1.4.3, in an environment that happened to have Bun lying around. The fix exists upstream, it is simply stuck there, so a commit pin is the pragmatic move until a new version ships. A shared base image is a dependency too, so check it when a build breaks over something your code never asked for.

Snags like this one slowing down your Rails upgrade? We can help.

Getting an MCP server running is the easy part. Every quickstart, in every language, gives you a server that runs as a subprocess on your own machine and disappears when the client exits. That’s enough to experiment locally, but it’s a long way from something a team can rely on. Once you want to deploy it, questions about where it runs, state management, authentication, and security become your responsibility. The Ruby SDK’s defaults don’t solve most of those problems, and one of them even comes with a published security advisory.

In this article, we’ll cover what changes when a Ruby MCP server stops being a subprocess: the two shapes it can take in a Rails shop, why session state breaks down when running behind multiple Puma workers, the DNS rebinding vulnerability the transport shipped with, and what the specification asks of you once a shared token is no longer enough.

From subprocess to service

MCP defines two transports. With stdio, the client launches your server as a subprocess and talks to it over standard input and output. It is the fastest way to see something working, but it puts a copy of the server on every machine that uses it. Everybody needs the code and credentials for the database, and every change means everybody pulls. Our marketing team uses these tools too, and “clone this repository and check your Ruby version” is not a reasonable thing to ask of them.

Streamable HTTP puts the server in one place instead. Everyone points a client at a URL, and an update is a deploy rather than an announcement.

One nice thing about the Ruby implementation is that the transport is just a Rack application, so everything else is familiar:

transport = MCP::Server::Transports::StreamableHTTPTransport.new(BlogServer.build)
mcp_token = ENV.fetch("MCP_AUTH_TOKEN")

app = Rack::Builder.new do
  map "/mcp" do
    use Auth::BearerToken, token: mcp_token
    run transport
  end

  map "/up" do
    run ->(_env) { [200, { "content-type" => "text/plain" }, ["ok"]] }
  end
end.to_app

run app

BlogServer.build is our own factory, a method that returns a fresh MCP::Server with our tools and resources already registered. The transport wraps that server, the token comes from the environment, and everything below those two lines is just Rack.

Nothing in this file knows it is serving MCP, which is exactly what we want. It means everything we already know about running Rack applications still applies.

Two shapes for a server

Once it is a service, there are two places it can live, and the choice has more consequences than it first appears.

Ours is standalone, because the data it serves lives in its own database, filled by a pipeline that reads both blog repositories. The server is a read-only layer over that, so it has no reason to be part of anything else, and a config.ru with Puma in front of it is the whole deployment.

The other shape is an MCP endpoint inside an application you already run, which is the more common case for a Rails team wanting to expose what their app already knows. The SDK supports two ways of doing it. The first mounts the transport in your routes, wrapping a server you have already built elsewhere:

transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)

Rails.application.routes.draw do
  mount transport => "/mcp"
end

That builds one server when the process boots, and every caller gets the same one. The second builds a server per request, in a controller:

class McpController < ActionController::API
  def create
    server = MCP::Server.new(
      name: "my_server",
      version: "1.0.0",
      tools: [SomeTool, AnotherTool],
      server_context: { user_id: current_user.id },
    )
    transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
    status, headers, body = transport.handle_request(request)

    render(json: body.first, status: status, headers: headers)
  end
end

That is more work per request, but it has a benefit you cannot get from the mounted version: current_user is in scope. The tool list can differ by caller, and server_context carries identity down into the tools themselves, which is what per-customer scoping is built on. If the server will ever answer to more than one account, this is the shape to start from, because retrofitting identity into a server built at boot means rebuilding it.

Living inside the Rails app buys two more things. You inherit whatever authentication is already there, and your tools read the same models as the rest of the application, so there is no second connection to configure and no schema drift between two codebases. What you give up is isolation: MCP traffic now shares workers and a deploy cycle with everything else the app does.

Sessions, and the trap in the Ruby SDK

Here is the part that makes this interesting: StreamableHTTPTransport stores session and SSE stream state in memory. The SDK’s own documentation is blunt about the consequence: it must run in a single process. Puma with workers > 0, or Unicorn, forks processes that do not share memory, and session management and open SSE connections break. Behind a load balancer, you need sticky sessions so that a client’s requests keep landing on the instance that remembers it.

The escape hatch is stateless: true, which drops the session requirement and works with any process configuration. It is what we pass, along with a Puma config that defaults to no workers anyway:

max_threads = ENV.fetch("MCP_MAX_THREADS", 5).to_i
threads max_threads, max_threads

workers_count = ENV.fetch("WEB_CONCURRENCY", 0).to_i
workers workers_count

if workers_count.positive?
  preload_app!

  on_worker_boot do
    ActiveRecord::Base.establish_connection(ENV.fetch("DATABASE_URL")) if defined?(ActiveRecord::Base)
  end
end

Threads by default, workers only if someone deliberately asks for them, and if they do, the Active Record connection gets re-established after the fork rather than inherited.

This whole area got simpler the day before this post went out. The 2026-07-28 specification removes protocol-level sessions and the Mcp-Session-Id header entirely, along with the initialize handshake. Any request can now land on any instance, which means the sticky routing and shared session stores that horizontal deployments used to need are no longer part of the picture. So stateless: true has stopped being a workaround and turned into a description of how the transport is supposed to behave. The single-process constraint above is only yours to worry about while you are on a gem release that still implements sessions, which is the first thing to check before planning a deployment around any of it.

Host and Origin are not optional

Earlier this month, the mcp gem got a security advisory, GHSA-rjr6-rcgv-9m7m, covering every version before 0.23.0. The Streamable HTTP transport processed every incoming JSON-RPC request without ever inspecting the HTTP Host or Origin headers.

That sounds mild until you think about where MCP servers actually run. A malicious page could use DNS rebinding to point its own hostname at 127.0.0.1 and then talk to an MCP server running on the visitor’s machine, invoking its tools and reading whatever they return. For a server with filesystem or credential access, that is sensitive data disclosure and, depending on the tool set, local action execution.

Version 0.23.0 added allowed_hosts and allowed_origins, and they are the reason those parameters appear in our transport:

transport = MCP::Server::Transports::StreamableHTTPTransport.new(
  BlogServer.build,
  stateless: true,
  enable_json_response: !ENV["MCP_SSE_RESPONSES"],
  allowed_hosts: allowed_hosts,
  allowed_origins: allowed_origins
)

An empty allowlist is not a safe default. On a current gem it means every request comes back with a 403, and on anything older than 0.23.0 it meant no check happened at all, so the two ways to get this wrong are a server nobody can reach and a server anybody can. Both look like a healthy process from the outside, so the file refuses to start rather than guess:

allowed_hosts = ENV.fetch("MCP_ALLOWED_HOSTS", "").split(",").map(&:strip).reject(&:empty?)

if allowed_hosts.empty? && ENV["RACK_ENV"] == "production"
  raise "MCP_ALLOWED_HOSTS is unset. Set it to this deployment's host name " \
        "(e.g. blog-mcp-rb.herokuapp.com) or every request will be rejected with a 403."
end

The same file does the same thing for a missing authentication token. Refusing to boot is an unfashionable pattern, but the alternative is a deployment that comes up green and is either open to the internet or broken for everyone, and neither is a state you want to learn about from a client. Noticing that you are on a vulnerable version in the first place is a separate concern, and bundler-audit is the tool for it. We covered it along with the rest of what we run in 4 Essential Security Tools for Rails Apps, and a young gem moving quickly is exactly the case it earns its keep on.

From a shared token to OAuth

Ours is an internal tool, so authentication is a shared bearer token checked by a Rack middleware:

def authorized?(env)
  scheme, value = env["HTTP_AUTHORIZATION"].to_s.split(" ", 2)
  return false unless scheme&.downcase == "bearer" && value

  Rack::Utils.secure_compare(value, @token)
end

Anything that fails gets a 401 with a WWW-Authenticate header, and nothing downstream runs. Rack::Utils.secure_compare rather than ==, because a plain string comparison returns as soon as two characters differ, which leaks how much of the token a caller got right. That is a floor. A shared token cannot tell one caller from another, cannot be scoped to part of the data, and cannot be revoked for one person without rotating it for everybody. The moment the server has users outside the team, or needs to know which of them is asking, you need OAuth.

That prospect sounds heavier than it is, because two separate questions tend to get run together. The first is what your server owes as an OAuth 2.1 resource server, and that part is yours no matter what. The second is who issues the tokens, and there the answer is usually somebody else: an identity provider you already pay for, a dedicated auth service, or your own application if it already does this. Your server does not issue tokens and does not run a login flow. What it owes is discovery and validation:

Four requirements are worth reading closely, because they are all on your side of the line. You MUST implement Protected Resource Metadata (RFC 9728), which is a JSON document naming the authorization servers that can issue tokens for you. Your 401 has to point at it:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="posts:read"

You MUST validate that an access token was issued specifically for you as the intended audience, per RFC 8707, and reject anything else. A token that is valid, unexpired, and meant for a different service is not a token you may accept, and this is the requirement most likely to be skipped by someone who has previously written “verify the JWT signature” and stopped there. When a token is valid but its scopes are not enough, the server should answer with a 403 carrying error="insufficient_scope" and the scopes the operation actually needs, so the client can ask for them rather than guess.

The client’s side of that diagram, the PKCE parameters and the redirect dance, is the client’s problem, and the ecosystem largely handles it.

Which leaves the question of who plays the authorization server, and the specification is deliberately quiet about it: any OAuth 2.1 provider will do, so Okta, Entra, Auth0, Keycloak and friends are all fair game, as is Doorkeeper in your own Rails app if it is already an OAuth provider. That is the reassuring part. The part worth checking before you commit is that “our users can already sign in with it” is not the same question. Signing people in is authentication of humans. What an MCP client needs is an authorization server that can issue an access token scoped to your server, which is a shorter list of capabilities than most provider comparison pages lead with:

• It publishes discovery metadata, either RFC 8414 or OpenID Connect Discovery, since clients are required to find its endpoints that way.
• A client can obtain a client ID, whether through Client ID Metadata Documents (what the specification now prefers), Dynamic Client Registration (allowed, and deprecated), or plain pre-registration by an administrator.
• It honors the resource parameter, so the token it issues is bound to your server as the audience rather than being a general-purpose token for the whole provider.

Not every provider does all three, and the one that catches people is registration. If yours has no dynamic registration, the fallback the specification allows is pre-registering each client out of band, which is fine for a handful of known clients and painful past that. It is worth knowing which of these you have before the auth decision is made for you by whatever is already in the app.

The SDK will not do any of this for you. It has no authentication story at all, which is the right call for a transport, and it means the work lands in Rack middleware or a before_action, both of which you have written before.

Limiting what a caller can reach

Authentication answers who is calling. What they can reach is a separate question, and a tool’s blast radius is whatever its query can touch.

Our server only reads, and every model says so:

class Post < ActiveRecord::Base
  self.table_name = "posts"

  belongs_to :source
  belongs_to :category
  has_one :content, class_name: "PostContent", foreign_key: :post_id

  def readonly? = true
end

That is one line per model, and it is a guard against the common case, an accidental save or update reached from a tool that was only ever meant to read. It is not a hard guarantee: update_all, delete_all, and raw SQL all skip the instance-level check entirely. What sits on the other end of the connection is a model with a set of tools, and the boundary between answering questions about the data and changing it deserves more than a single override, a database user with no write grants being the actual floor.

For a server with more than one customer, the same principle applies to rows rather than to writes, and server_context is how identity gets there. A tool receives it as a keyword argument, which means scoping is a where clause like any other:

def self.call(query:, server_context:)
  posts = Post.where(account_id: server_context.fetch(:account_id))
  # ...
end

fetch rather than [] on purpose. If the context is ever missing an account, that should raise rather than quietly return a relation scoped to nil. The rule underneath is: never ask a description to enforce something a query can enforce. A model that is told to only look at one account will usually comply, but usually is not a security control.

Testing

Start with the cheapest question there is, which is whether the MCP server is running at all:

curl http://127.0.0.1:9292/up

That is the health endpoint from the Rack file, and it answers without going anywhere near the transport, so a failure there is Puma or boot configuration rather than anything to do with MCP.

For the protocol itself, the MCP Inspector connects the way a client would. It is a Node tool, so testing a Ruby server means having npx around. It has a browser UI, and it also has a CLI mode which takes the same arguments a client would use, prints the JSON-RPC result, and can go in a script. Listing the tools over HTTP, with the token:

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:9292/mcp \
  --transport http --header "Authorization: Bearer $MCP_AUTH_TOKEN" \
  --method tools/list

Reading one of our own resource URIs, which exercises a different path through the server:

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:9292/mcp \
  --transport http --header "Authorization: Bearer $MCP_AUTH_TOKEN" \
  --method resources/read --uri "blog://fastruby.io/style-guide"

Those two are worth running every time you change something. tools/list is the only place you see your tool descriptions and input schemas the way a client actually receives them, which is a different experience from reading them in the source, and it will show you an enum that quietly became a string or an optional parameter that became required. resources/read goes through the read handler and, for us, the files on disk, which is where a bad path or a bad encoding turns up. Both commands also test the middleware, because they are going through it. Run either one with the token changed by a character and you should get a 401 rather than a result, on the real path, with no mocking involved.

Locally, the stdio entry point is still the fastest thing to point the Inspector at, since it needs no server running at all:

npx @modelcontextprotocol/inspector bundle exec ruby server.rb

One warning about debugging any of this. When something goes wrong inside a handler, what comes back is “Internal error” and nothing else, and the detail is on stderr.

Conclusion

In this article, we went through what a Ruby MCP server needs once it stops being a subprocess: Streamable HTTP instead of stdio, a choice between a standalone service and an endpoint inside an existing Rails app, statelessness so it survives more than one Puma worker, Host and Origin validation that a security advisory made mandatory, a shared token as the internal floor with OAuth as the answer beyond it, and read-only models and server_context deciding what any caller can actually reach.

Almost none of that is protocol code. It is Rack, Puma, OAuth, and being careful about what your tools can touch, which is to say it is the work you already know how to do. The MCP-specific part is small, and the parts most likely to hurt you are the ones that look like configuration.

Two caveats worth carrying. The gem is young and its API has moved between releases, so pin it and re-read the changelog rather than trusting a snippet you found, including these. And the specification itself moved this week, so anything written about sessions before the 2026-07-28 revision is now describing a protocol that no longer exists.

Are you looking at putting an MCP server in front of your Rails application’s data and wondering what it takes to do it safely? Talk to us today!

This one is different. The patched version of Active Storage will not run on an old copy of libvips. It raises an exception during boot and refuses to start:

/usr/local/bundle/gems/activestorage-8.1.3.1/lib/active_storage/vips.rb:36:in '<compiled>': libvips's unfuzzed operations are not safe to use with untrusted content, and Active Storage cannot disable them. Disabling them requires libvips 8.13 or later and ruby-vips 2.2.1 or later. Please upgrade libvips and ruby-vips, or remove the ruby-vips gem from your Gemfile. (RuntimeError)

libvips is a system library that lives in your container image, not a gem in your Gemfile, so bumping the gem does nothing on its own until you rebuild the image. If your image still ships the old library, you are in one of two states, and neither is the one you think you are in: either your app won’t boot, or it never received the patched gem at all and is quietly still vulnerable.

In this post, you’ll learn why upgrading activestorage doesn’t close CVE-2026-66066 on its own, how a stale container image both hides the vulnerability and blocks the fix, and why rebuilding on the wrong base still leaves you exposed.

The CVE, and why the gem bump isn’t the whole fix

CVE-2026-66066 is a vulnerability in the way Active Storage processes image variants. When Active Storage generates a variant, a thumbnail or a resized copy, it hands the work off to libvips, a fast image-processing library. The trouble is that some of libvips’s operations are not safe to run on untrusted input, and older versions of the library give you no way to turn those operations off. An attacker who can get your app to process a malicious file can abuse this. The official Rails advisory describes the impact as unauthenticated arbitrary file read that can escalate to remote code execution. Its severity rating is Critical, and public write-ups of the exploit are already circulating.

As of early August 2026 it is not yet listed in CISA’s Known Exploited Vulnerabilities catalog, but that is not a reason to relax. Arbitrary file read on a production host usually means your credentials and environment variables are readable, which is often enough for an attacker to move further into your infrastructure.

If you use Active Storage with image variants, you are very likely affected. The vips processor has been the default variant processor since config.load_defaults 7.0, and it has stayed the default since, so most modern Rails apps rely on it without ever opting in. The versions that carry the fix are activestorage 7.2.3.2, 8.0.5.1, and 8.1.3.1.

Patching the gem is normally the reliable fix for a Rails CVE, and usually that is where the story ends (we have written before about several Rails CVEs worth checking). If your app is on an end-of-life branch like 7.0 or 7.1, there is no patched release to bump to at all, and your only options are upgrading libvips together with the mitigation below, or upgrading Rails to a supported version.

The fix is genuinely both/and: you need the patched activestorage and you need libvips 8.13 or newer, because libvips 8.13 is the first version that can block those unsafe operations. Patched Active Storage checks for that capability when it boots, and if libvips is too old it raises the exception I showed above and refuses to start rather than run in what the advisory calls an “unsecurable environment”. The newer library does the actual securing; the gem only knows how to ask for it.

If you can’t bump the gem right away, the advisory documents two workarounds that still require libvips 8.13 or newer: calling Vips.block_untrusted(true) from an initializer (with ruby-vips 2.2.1 or newer), or setting the VIPS_BLOCK_UNTRUSTED environment variable, which libvips reads at initialization.

And if there is any chance your app processed a malicious upload before you patched, rotate whatever secrets were reachable from that host. To find out whether that actually happened, Rails published forensic tooling that scans your Active Storage blobs for the crafted files the attack depends on and estimates how long you were exposed, though the maintainers note a clean result is strong evidence rather than proof.

The proof: same gem, two images

To make the problem concrete, I built a small demo: one Rails app, one Dockerfile, and two images that differ in exactly one thing. The app has the patched activestorage (8.1.3.1) and Active Storage configured with the vips variant processor. The boot check fires from the configuration and the environment, not from a request.

The Dockerfile takes the Debian suite as a build argument, so the only thing that changes between the two builds is the base image, and therefore the version of libvips that apt installs:

# syntax=docker/dockerfile:1
ARG RUBY_VERSION=3.4
ARG SUITE=bookworm
FROM docker.io/library/ruby:${RUBY_VERSION}-slim-${SUITE}

# libvips comes from the OS package repo, NOT from a gem.
# The base image (SUITE) decides which libvips version you get:
#   bullseye -> 8.10.x (< 8.13, cannot block untrusted ops)
#   bookworm -> 8.14.x (>= 8.13, can)
RUN apt-get update -qq \
 && apt-get install --no-install-recommends -y build-essential git libvips libvips-tools libpq-dev pkg-config \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .

ENV RAILS_ENV=production \
    SECRET_KEY_BASE_DUMMY=1

# Print the receipts, then boot.
CMD ["bash", "-lc", "echo '== libvips =='; vips --version; echo '== activestorage =='; bundle list | grep activestorage; echo '== boot =='; bin/rails runner 'puts :booted_ok'"]

Then I built the same file twice, changing only the suite:

docker build -f Dockerfile.demo --build-arg SUITE=bookworm -t asdemo:new .
docker build -f Dockerfile.demo --build-arg SUITE=bullseye -t asdemo:old .

Each container prints its libvips version, confirms which activestorage is installed, and then tries to boot the app. Running the bookworm image first:

$ docker run --rm asdemo:new
== libvips ==
vips-8.14.1
== activestorage ==
  * activestorage (8.1.3.1)
== boot ==
booted_ok

libvips 8.14.1, the patched gem, and a clean boot. Now the bullseye image, which is identical except that apt installed an older libvips:

$ docker run --rm asdemo:old
== libvips ==
vips-8.10.5-Wed Apr 30 17:29:54 UTC 2025
== activestorage ==
  * activestorage (8.1.3.1)
== boot ==
/usr/local/bundle/gems/activestorage-8.1.3.1/lib/active_storage/vips.rb:36:in '<compiled>': libvips's unfuzzed operations are not safe to use with untrusted content, and Active Storage cannot disable them. Disabling them requires libvips 8.13 or later and ruby-vips 2.2.1 or later. Please upgrade libvips and ruby-vips, or remove the ruby-vips gem from your Gemfile. (RuntimeError)
        ... backtrace trimmed ...

But the bullseye image ships libvips 8.10.5, which is older than 8.13, so patched Active Storage does exactly what the advisory says it will and refuses to boot. To rule out the gem layer, ruby-vips is 2.3.0 in both images and the Gemfile.lock is identical. The only moving part is the system library. The same patched Gemfile produced one app that boots and one that won’t.

Rebuilding the image isn’t always enough

The obvious fix is to rebuild the image, and that is the right instinct, but it comes with a trap. Rebuilding only helps if the base image you rebuild on actually carries a newer libvips, and Debian bullseye does not. Checking the bullseye base while writing this, apt still installed libvips 8.10.5, the same version the demo hit. bullseye is an older Debian release, and its package repositories, security updates included, are effectively frozen at libvips 8.10, so a rebuild faithfully reinstalls exactly what is there.

The version of libvips you get is really a property of the base image’s distribution, not of how recently you rebuilt. To get a patched version of libvips, you have to move to a base whose repositories carry it. Moving from bullseye to bookworm is the simplest path, since bookworm ships libvips 8.14. If you are pinned to an older distribution for another reason, compiling a newer libvips yourself is the alternative, though moving the base image to bookworm is usually less work and less to maintain afterward.

A rebuild that stays on the same old base is not a fix; it just reproduces the vulnerable environment with a fresh timestamp.

The image that quietly stays vulnerable

There is a worse case than the app that refuses to boot, and it is the quiet one. The image that raises on boot at least tells you something is wrong, because the app is down and you notice right away. The dangerous image is the one that was never touched at all. It still runs the old, unpatched activestorage on the old libvips, it boots perfectly, and it keeps serving traffic while remaining fully exploitable. Nobody gets an exception, and nothing looks broken.

The instinct is to reach for image age to find these, but the age of a tag does not tell you what you need to know. An image tagged last week can still be built on a base that is two years old, and an image built months ago might be sitting on a perfectly current base. What you actually care about is whether the image was rebuilt since the base it depends on last changed. An image that has fallen behind its own base has missed whatever security updates that base shipped, libvips among them, even if its tag looks recent.

This is the same kind of blind spot we write about on the gem side. A tool like bundler-audit scans your Gemfile.lock for known-vulnerable gems, but it reads the lockfile, so it has no way of knowing which version of libvips your base image installed.

In our experience auditing client deployments, stale base images are the rule rather than the exception. CVE-2026-66066 is a good reason to check whether your own images have drifted, and to make rebuilding them a habit rather than a one-time scramble.

Conclusion

The fix for CVE-2026-66066 requires two things: the patched gem and a base image that ships libvips 8.13 or newer. Patching the gem without rebuilding the image leaves you in one of two bad states. Image drift is not a problem you fix once because base images drift the same way gems do, and the only thing that keeps them current is a rebuild cadence you actually stick to.

We can help you audit what your deployed images are actually running and find the gaps your Gemfile cannot see. Send us a message!

Now in 2026, for the real fans, it’s possible you’re still using sass-rails and you’re full of these files around your project. So if you still want to keep using it like me, I recommend migrating to Dart Sass, which is, in fact, a simple migration, to avoid headaches in the future and, most importantly, to start using the latest features.

Historical context

To give a bit of context, you may remember that sass-rails has been the default SCSS library since Rails 3.1 (2011). Some engineers like me were using Sass before that, but that’s when it became a Rails standard.

Behind it, sass-rails originally used the Ruby implementation of Sass (the original sass gem). That implementation reached its end-of-life in 2019, so starting with Rails 6 the default moved to sassc-rails, which used LibSass, the C/C++ port of the Sass compiler. LibSass was built to be a faster and more portable alternative to the original Ruby-based compiler.

However, LibSass reached its official end-of-life (EOL) in October 2025 too. So now the recommendation is to migrate to Dart Sass, which includes more features and better CSS compatibility. As the name says, it’s built in the Dart language, and the wrapper tool uses the standalone Dart Sass executable, meaning you don’t even need Node.js installed to use it.

Why keep using Dart Sass?

A fair question in 2026 is why bother with Sass at all when modern CSS already has native variables, nesting, and more. The honest answer: if your project already runs on SCSS, a full rewrite to plain CSS is a big effort with little payoff.

Dart Sass is also the only Sass implementation still maintained. It’s the reference now, it gets all the new features first, and it keeps the same partials, mixins, and functions you already use. So instead of throwing away years of styles, you keep them and stay on a tool that’s still alive.

What Changes in Dart Sass

These are the most important changes.

/ division operator deprecated (biggest breaking change)

Maybe you never noticed, but the slash / operator has two behaviors: on one hand, it works as division, but in another context, it works as a separator. You can imagine the migraine for the devs maintaining that.

$container-width: 1200px;
$grid-columns: 12;

.sidebar {
  // as divisor
  width: $container-width / $grid-columns;

  // as separator
  font: 16px / 1.5 sans-serif;
}

For division, you now use math.div():

@use 'sass:math';

.sidebar {
  width: math.div($container-width, $grid-columns);
}

And when you actually want a slash separated list with variables, you use list.slash():

.sidebar {
  font: list.slash($font-size, $line-height) sans-serif;
}

@import deprecated in favor of @use and @forward

You probably also didn’t notice that when you do an @import foo on a file, all the imported values are loaded into the global namespace. That means, for example, that all the functions become available globally. If you’re experienced enough (and if not, just trust us), having everything available, especially on medium or big projects, can soon become a mess of cascading rules overwriting each other. It makes compilation slow as a consequence of importing the same file multiple times, and it increases the complexity of knowing where a variable or function came from.

The good news is that for you it just means starting to replace @import foo with @use foo.

Imagine you have one file where you define the variables:

// _variables.scss
$brand-color: #ff0000;

On the other side, you have a file with a few functions, but it also uses the variables:

// _mixins.scss
@import "variables";

@mixin brand-border {
  border: 2px solid $brand-color;
}

Here, brand-border is available globally. In your file you’d use it by doing:

@import "variables";
@import "mixins"; // Works because everything is globally leaked

.button {
  color: $brand-color;
  @include brand-border;
}

Now, with the latest version, the code looks similar:

@use "variables"; // Load variables for main.scss
@use "mixins";    // Load mixins for main.scss

.button {
  color: variables.$brand-color; // Uses variables namespace
  @include mixins.brand-border;   // Uses mixins namespace
}

Now it’s using namespaces and nothing is globally available.

Other breaking changes

Finally, there’s a list of more breaking changes here, but if you’re working on a Rails project, the most typical ones are:

Math functions now require an explicit module import:

// Before
$value: round(1.5);
$half: floor(10px / 2);

// After
@use 'sass:math';

$value: math.round(1.5);
$half: math.floor(math.div(10px, 2));

Color functions are deprecated in favor of the sass:color module:

// Before
$dark: darken(#036, 10%);
$light: lighten(#036, 10%);

// After
@use 'sass:color';

$dark: color.adjust(#036, $lightness: -10%);
$light: color.adjust(#036, $lightness: 10%);

Other modules like sass:string, sass:list, and sass:map follow the same pattern. Also, global functions like str-length(), map-get(), and map-keys() now require an explicit @use declaration.

Using the Migrator

Luckily there’s a Sass Migrator that automatically updates your files to make it easier to migrate your project.

You can install it with npm install -g sass-migrator. After that, if your base file is application.scss, you can run it like this:

sass-migrator module --migrate-deps app/assets/stylesheets/application.scss

There are a few options there. The first useful one is --migrate-deps, which tells the migrator to update both the explicitly specified stylesheets and any dependencies linked via @use, @forward, or @import rules.

A few Rails tips

Once you switch to the dartsass-rails gem, a couple of things saved us headaches.

First, register any extra SCSS entry point in config/initializers/dartsass.rb. The gem builds application.scss by default, but any other entry point you have (an admin stylesheet, a separate theme, etc.) won’t be compiled by Dart Sass unless you add it here. If you forget, those files won’t be compiled into CSS at all, or Sprockets will throw an error since it no longer has a Sass compiler to process them:

Rails.application.config.dartsass.builds.merge!(
  "admin.scss" => "admin.css",
  "theme.scss" => "theme.css"
)

Second, third-party files you don’t control will still throw deprecation warnings. Use --quiet-deps to silence the noise from those while keeping warnings for your own code:

Rails.application.config.dartsass.build_options << "--quiet-deps"

And once your own code is clean, turn the deprecations you already fixed into build errors so they don’t creep back in:

Rails.application.config.dartsass.build_options << "--fatal-deprecation=import"
Rails.application.config.dartsass.build_options << "--fatal-deprecation=mixed-decls"

Conclusion

Migrating from Sass Rails to Dart Sass isn’t as scary as it sounds. The Migrator does most of the heavy lifting, and the rest is mostly swapping @import for @use and adding a few module imports. Do it now while it’s still a small migration, and you get to keep your SCSS files and stay on a tool that’s actually maintained.

Planning a bigger Rails upgrade and want a hand? We can help you get there!

In a previous post, we introduced Rails.event.notify(...), the tool-agnostic Event Reporter shipping in Rails 8.1. In this post, we’ll put it to work on a real problem: instrumenting every LLM call in your app so token usage, latency, and cost become structured events you can log, graph, and forward to any APM or data warehouse.

Why instrument LLM calls?

Before writing any code, it helps to be specific about what we’re after. Four things, really. Cost, from the raw token counts up to the dollar figure on the invoice. Latency, so a slow model or a bloated prompt shows up before your users feel it. Failures, because a timeout or a rate limit shouldn’t just vanish. And, most of all, attribution: not just that a call happened, but which feature, user, and request set it off.

ActiveSupport::Notifications could get us there, but we’d be writing custom glue code for every APM vendor. The Event Reporter gives us one structured emission point instead, and lets each subscriber decide what to do with it.

Prerequisites: This tutorial assumes Rails 8.1 (for Rails.event) and any LLM client that reports token usage. The examples use the ruby_llm gem, but the pattern works with the official anthropic/openai SDKs or a raw Net::HTTP call just as well.

The starting point: an uninstrumented service

Here’s a typical, uninstrumented service that summarizes some text:

# app/services/summarizer.rb
class Summarizer
  MODEL = "claude-haiku-4-5"

  def initialize(text)
    @text = text
  end

  def call
    chat = RubyLLM.chat(model: MODEL)
    response = chat.ask("Summarize the following text:\n\n#{@text}")
    response.content
  end
end

It works, but it’s a black box. We have no idea how many tokens that summary consumed, what it cost, or how long the LLM took to respond. Let’s improve that.

Emitting a structured event around the call

The Event Reporter’s core method is Rails.event.notify(name, payload). We wrap the call, measure the duration with a monotonic clock, and emit everything we care about:

# app/services/summarizer.rb
class Summarizer
  MODEL = "claude-haiku-4-5"

  def initialize(text)
    @text = text
  end

  def call
    started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

    chat = RubyLLM.chat(model: MODEL)
    response = chat.ask("Summarize the following text:\n\n#{@text}")

    duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round

    Rails.event.notify(
      "llm.completion",
      model: MODEL,
      input_tokens: response.input_tokens,
      output_tokens: response.output_tokens,
      total_tokens: response.input_tokens + response.output_tokens,
      duration_ms: duration_ms
    )

    response.content
  end
end

Every summary now publishes a single llm.completion event. Notice what we don’t put in the payload: no prompt text, no user content. Keep payloads small and free of PII, just IDs, token counts, and durations.

Listening with a subscriber

An event that no one listens to does nothing. Subscribers are plain Ruby objects that implement an #emit(event) method, where event is a hash containing :name, :payload, :tags, :context, :timestamp, and :source_location.

Let’s start with a subscriber that writes a compact key=value log line and forwards metrics to an APM. It lives under app/subscribers/, so Rails autoloads it:

# app/subscribers/llm_event_subscriber.rb
class LlmEventSubscriber
  def emit(event)
    return unless event[:name] == "llm.completion"

    payload = event[:payload]

    Rails.logger.info(
      "[llm.completion] model=#{payload[:model]} " \
      "tokens=#{payload[:total_tokens]} " \
      "duration_ms=#{payload[:duration_ms]}"
    )

    # Forward to your APM of choice (Datadog, AppSignal, New Relic, etc.):
    MyAPM.distribution(
      "llm.duration_ms",
      payload[:duration_ms],
      model: payload[:model]
    )
    MyAPM.counter(
      "llm.total_tokens",
      payload[:total_tokens],
      model: payload[:model]
    )
  end
end

Then register an instance once, at boot:

# config/initializers/llm_events.rb
Rails.event.subscribe(LlmEventSubscriber.new)

The same event now lands in your logs and your dashboards, without the service object knowing anything about AppSignal, Datadog, or New Relic. Swap the subscriber’s body and you’ve swapped vendors.

From tokens to dollars

Tokens are only half the story. The number your finance team cares about is cost. Providers charge different rates for input and output tokens: the prompt you send costs less, the text the model generates back costs more. The exact rates vary by model. So we keep a small lookup table that maps each model to its two rates, in the same units the pricing pages use: U.S. dollars per one million tokens.

There’s a catch, though: a hand-maintained table like this goes stale fast. Providers release new models and adjust prices regularly, and every change means another edit to keep in sync. If you’re using ruby_llm, you can skip the table entirely. The gem keeps its own pricing registry and calculates cost for you: a response exposes response.cost.total, and model.cost_for(response.tokens) returns a RubyLLM::Cost broken down by component, input, output, cache_read, cache_write, thinking and the total across all of them. When your client hands you cost directly, emit that value and let the gem take care of staying current.

Not every LLM client reports cost, though, so it’s worth knowing how to compute it yourself. In that case we keep the table and the math inside the subscriber, so cost is computed once and every consumer of the event gets it for free:

# app/subscribers/llm_event_subscriber.rb
class LlmEventSubscriber
  # Per-model pricing in USD per 1 million tokens.
  #   input  => rate for the tokens you send (the prompt)
  #   output => rate for the tokens the model generates back
  # Copy these numbers from your provider's pricing page and keep them in sync.
  PRICING = {
    "claude-haiku-4-5" => { input: 1.00, output: 5.00 },
    "claude-sonnet-5"  => { input: 3.00, output: 15.00 }
  }.freeze

  def emit(event)
    return unless event[:name] == "llm.completion"

    payload = event[:payload]
    cost = estimate_cost(payload)

    Rails.logger.info(
      "[llm.completion] model=#{payload[:model]} " \
      "tokens=#{payload[:total_tokens]} " \
      "duration_ms=#{payload[:duration_ms]} " \
      "cost_usd=#{cost.round(6)}"
    )

    # The duration_ms and total_tokens metrics are
    # omitted to keep the example focused on cost.

    MyAPM.distribution(
      "llm.cost_usd",
      cost,
      model: payload[:model]
    )
  end

  private

  def estimate_cost(payload)
    prices = PRICING[payload[:model]]
    return 0.0 unless prices

    input_cost = payload[:input_tokens] * prices[:input] / 1_000_000.0
    output_cost = payload[:output_tokens] * prices[:output] / 1_000_000.0
    input_cost + output_cost
  end
end

The registration in the initializer stays exactly the same. Now every completion carries a dollar figure you can sum, chart, and alert on.

Attributing calls to features and users

Aggregate token counts are useful, but “which feature is eating my budget?” and “how much did this user cost this month?” are the questions that actually drive decisions. The Event Reporter answers both with two mechanisms: tags and context.

Tags help identify which feature or operation triggered the call. Wrap the call in Rails.event.tagged, using a keyword so the tag carries a real value rather than just a label:

# app/services/summarizer.rb
def call
  Rails.event.tagged(feature: "summarization") do
    # ...measure and notify as before...
  end
end

Context describes the environment an event happens in, and it’s typically set once per request. A great place is a controller before_action or the base controller:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :set_llm_context

  private

  def set_llm_context
    Rails.event.set_context(
      request_id: request.request_id,
      user_id: current_user&.id
    )
  end
end

From now on, every llm.completion event automatically carries the tags and context, with no extra work in the service object. A full event handed to your subscriber now looks like this:

{
  name: "llm.completion",
  payload: {
    model: "claude-haiku-4-5",
    input_tokens: 2000,
    output_tokens: 500,
    total_tokens: 2500,
    duration_ms: 842
  },
  tags: { feature: "summarization" },
  context: { request_id: "abc123", user_id: 456 },
  timestamp: 1738964843208679035,
  source_location: { filepath: "app/services/summarizer.rb", lineno: 14, label: "Summarizer#call" }
}

Update the subscriber to read them:

def emit(event)
  return unless event[:name] == "llm.completion"

  payload = event[:payload]
  # `tags` is a hash. Because we tagged with `feature:`, we can read the value
  # straight from the :feature key, with no assumptions about ordering.
  feature = event[:tags][:feature]
  user_id = event[:context][:user_id]

  Rails.logger.info(
    "[llm.completion] feature=#{feature} user_id=#{user_id} " \
    "model=#{payload[:model]} cost_usd=#{estimate_cost(payload).round(6)}"
  )
end

A reusable instrumentation helper

By now we’ll want this measure-and-notify block around every LLM call, not just the summarizer. Let’s extract it into a helper so every call site stays consistent:

# app/services/llm_instrumentation.rb
module LlmInstrumentation
  # Wraps any block that returns an object responding to
  # #input_tokens and #output_tokens, and emits an llm.completion event.
  def self.instrument(model:, feature:)
    Rails.event.tagged(feature: feature) do
      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

      response = yield

      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round

      Rails.event.notify(
        "llm.completion",
        model: model,
        input_tokens: response.input_tokens,
        output_tokens: response.output_tokens,
        total_tokens: response.input_tokens + response.output_tokens,
        duration_ms: duration_ms
      )

      response
    end
  end
end

The service object shrinks back to almost what we started with, now fully instrumented:

# app/services/summarizer.rb
class Summarizer
  MODEL = "claude-haiku-4-5"

  def initialize(text)
    @text = text
  end

  def call
    response = LlmInstrumentation.instrument(model: MODEL, feature: "summarization") do
      RubyLLM.chat(model: MODEL).ask("Summarize the following text:\n\n#{@text}")
    end

    response.content
  end
end

Capturing the failures

Surfacing failed calls is just as important as tracking successful ones. Emit a separate event on error so timeouts and rate limits don’t disappear silently:

# app/services/llm_instrumentation.rb
def self.instrument(model:, feature:)
  Rails.event.tagged(feature: feature) do
    started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

    begin
      response = yield
    rescue => error
      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
      Rails.event.notify(
        "llm.error",
        model: model,
        error_class: error.class.name,
        duration_ms: duration_ms
      )
      raise
    end

    duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round

    Rails.event.notify(
      "llm.completion",
      model: model,
      input_tokens: response.input_tokens,
      output_tokens: response.output_tokens,
      total_tokens: response.input_tokens + response.output_tokens,
      duration_ms: duration_ms
    )

    response
  end
end

Add a branch to your subscriber for "llm.error", and now your dashboards show a failure rate alongside cost and latency, three basic signals that you need to observe on every LLM-powered feature.

Feeding a data warehouse

Because the payloads are already structured, a warehouse-oriented subscriber is just another #emit implementation. Buffer the events and ship them to your analytics pipeline:

# app/subscribers/warehouse_subscriber.rb
class WarehouseSubscriber
  def emit(event)
    return unless event[:name].start_with?("llm.")

    LlmEventBufferJob.perform_later(
      name: event[:name],
      payload: event[:payload],
      tags: event[:tags],
      context: event[:context],
      timestamp: event[:timestamp]
    )
  end
end

Register it alongside the first subscriber, in the same initializer:

# config/initializers/llm_events.rb
Rails.event.subscribe(LlmEventSubscriber.new)
Rails.event.subscribe(WarehouseSubscriber.new)

Once the data lands, per-user cost reports, per-feature budgets, and model A/B comparisons are all just queries.

Best practices for LLM events

A few habits keep this instrumentation clean as it grows. Stick to a clear resource.action namespace, like llm.completion and llm.error, so related events group together. Keep payloads free of PII. Compute cost in the subscriber rather than at the call site, so pricing lives in one place and your service objects don’t need to know about it. Instrument once through a shared helper, so every call site emits consistent events. And always instrument failures, because an error rate is as important as a cost figure.

Conclusion

LLM features don’t have to be black boxes. One Rails.event.notify call in the right spot turns an opaque API request into an event you can log, cost out, graph, or ship to a warehouse, and none of your service objects have to know where it ends up. As AI keeps creeping into your latency budget and your monthly bill, that visibility is what stops it from getting away from you.

Building AI features into your Rails app, or getting to Rails 8.1 so you can use the Event Reporter? Let’s talk.