Quickstart

Check your first flag from Ruby in under a minute.

1. Get your server key

In the dashboard, open Settings → API keys and copy the server key:

ck_srv_prod_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

Keep it in an environment variable. Never put it in code that ships to a client — the gem requires a server key and refuses the publishable ck_client_… key at startup. The key also picks the environment: production key, production rules.

2. Install

# Gemfile
gem "lucerna"

Ruby 3.2+, no runtime dependencies. Rails, Sinatra, Sidekiq and plain scripts all work — Rails needs no extra wiring.

3. Configure once

# config/initializers/lucerna.rb — or anywhere before first use
Lucerna.configure do |config|
  config.server_key = ENV["LUCERNA_GATES_KEY"]
end

The first check builds one shared client and starts a background refresh — like a database connection, there is exactly one per process.

4. Use it

Say who the user is, then check gates anywhere:

# one identity per request — who is this check for?
identity = Lucerna::Identity.new(
  user_id: current_user.id.to_s,
  email: current_user.email,
  traits: { plan: current_user.plan },
)

# Feature flag → true / false
if Lucerna.gates.flag("new_billing", identity)
  # show the new billing page
end

# Kill switch → false means the path is killed
unless Lucerna.gates.switch("payments")
  return render json: { error: "payments_paused" }, status: 503
end

# Experiment → variant name, or nil if the user isn't in it
variant = Lucerna.gates.experiment("checkout_test", identity)

# Send the user to People (powers targeting and audiences)
Lucerna.identity.identify(identity)

Checks are instant — no network call — and they never raise. Changes you make in the dashboard reach the gem within 10 seconds.

5. On shutdown

Nothing to do: the gem registers an at_exit hook that stops the refresh and flushes pending events. Running Puma in cluster mode, Unicorn, or Sidekiq? Forked workers heal themselves too — see forking servers.

That's it. Next: the Ruby SDK reference.