From first flag to local evaluation.

Setting up with an AI agent

Hand this guide to your coding agent.

Copy a ready-made prompt containing the install steps, the actor-identity decision, the five gates, group predicates, and the verification order from this page. Paste it into Claude Code, Cursor, Copilot, or any agent with repository access. It is written to keep the SDK key out of your repository and to stop for confirmation before anything reaches production.

You are adding ToggleFleet - a hosted feature-flag service - to a Ruby
application for the first time. Work strictly in the order below and stop for
confirmation before anything is enabled in production.

CRITICAL CONSTRAINTS - do not violate these:
1. The SDK key is a server-side secret. It must never appear in browser
   JavaScript, a mobile bundle, a committed file, a log line, or a test fixture.
   Read it from the environment only.
2. Do not call the ToggleFleet HTTP API from a request path. The gem evaluates
   flags in-process; a flag check must not make a network request.
3. Every flag ships OFF. Add the code path behind a flag that is off, then turn
   it on from the dashboard.
4. If you cannot determine something with certainty - which actor ID to use,
   whether a code path is safe to gate - say so and stop. Do not guess.

HOW IT WORKS (this shapes every decision below)
The process fetches the whole environment configuration once, refreshes it in
the background with conditional (ETag) requests, and evaluates flags locally. A
check is a hash lookup, not an HTTP call. If ToggleFleet is unreachable the
last-good configuration keeps being used; before the first successful fetch,
flags return config.default.

THE FIVE GATES - a flag is ON if ANY gate matches, evaluated in this order:
  boolean              on for every evaluation
  actor                an explicit list of stable actor IDs
  group                a group name whose predicate you register in Ruby
  percentage_of_actors deterministic per (flag, actor) - sticky, use for rollouts
  percentage_of_time   random per call - NOT sticky, use for sampling only
Gate state is per environment. There is nothing else - no expression language.

STEP 1 - KEY (write it into no file)
One SDK key per environment, generated in Settings -> SDK keys and shown once.
Put it in whatever secret mechanism this app already uses, as
TOGGLEFLEET_SDK_KEY. Tell me which environment's key you have been given and
confirm before continuing.

STEP 2 - INSTALL
  gem "togglefleet", "~> 0.2"     # MIT, no runtime dependencies, Ruby >= 3.0
config/initializers/togglefleet.rb:
  ToggleFleet.configure do |config|
    config.sdk_key          = ENV.fetch("TOGGLEFLEET_SDK_KEY")
    config.default          = false  # result when a flag is unknown or not yet loaded
    config.refresh_interval = 15     # seconds, jittered +/-15%
    config.open_timeout     = 3
    config.read_timeout     = 5
    config.logger           = Rails.logger
  end
  ToggleFleet.start               # background refresh; fork-safe as of v0.2.0
Do NOT add on_worker_boot wiring for Puma, Unicorn or Passenger. The client
detects a forked child and restarts its own refresh thread.

STEP 3 - ACTOR IDENTITY (decide this BEFORE writing any flag check)
ToggleFleet derives the actor ID from, in order: #togglefleet_id, then #id, then
#to_s. Whatever that returns is both the string actor gates match on AND the
input to percentage bucketing - so changing it later re-shuffles who is inside a
rollout. Choose one now and state which:
  - the bare id (the default, nothing to write), or
  - define togglefleet_id on the actor class for a namespaced or UUID identity.

STEP 4 - GROUPS (only if the app needs them)
Group membership is decided by YOUR code; ToggleFleet stores only the group name
enabled for a flag, and no actor attribute ever leaves the process. Register
predicates in the initializer, before any evaluation:
  ToggleFleet.register_group(:admins)   { |user| user.admin? }
  ToggleFleet.register_group(:internal) { |user| user.email.end_with?("@yourco.com") }
A predicate that raises is logged and treated as not matching. Keep them cheap
and free of side effects - they run on every evaluation that reaches the group
gate.

STEP 5 - GATE THE CODE PATH
  if ToggleFleet.enabled?(:checkout_v2, actor: current_user)
    render "checkout/v2"
  else
    render "checkout/current"
  end
Rules:
  - Pass actor: whenever an actor exists. Without one, the actor and
    percentage-of-actors gates cannot match.
  - Use groups: [:eu] only for a group that no registered predicate can derive
    from the actor.
  - The else branch must be the current, working behaviour. Do not gate a path
    whose off state is broken.
  - Keep the flag key a literal symbol at the call site so it stays greppable.
  - Need every flag at once (e.g. to bootstrap a client-side payload)? Use
    ToggleFleet.all(actor: current_user) server-side. Never ship the key to a
    browser to let it evaluate for itself.

STEP 6 - VERIFY (stop and ask me before turning anything on in production)
  - In tests, keep the network out: stub ToggleFleet.enabled? per example, or
    rely on config.default and assert the off path.
  - Exercise BOTH branches in development or staging.
  - Confirm the environment's "Last connected" time in Settings has updated.
  - If the app has metrics, attach them:
      config.on_evaluation = ->(flag, actor, result) {
        StatsD.increment("feature_flag.#{flag}.#{result}")
      }

REST API - only for services that cannot use the gem
  GET /v1/config    whole environment + ETag; send If-None-Match, expect 304
  GET /v1/evaluate  ?flag=&actor=&groups= for a single decision
Authorization: Bearer $TOGGLEFLEET_SDK_KEY, 600 requests/min per IP. There is
deliberately no browser CORS: the key reads the entire environment config.
Prefer /v1/config plus local evaluation over per-check /v1/evaluate calls.

DELIVERABLES:
- the actor-identity decision and why
- every flag key created, and what its off state does
- every file changed
- confirmation that the SDK key appears in no committed file
- anything you were unsure about - say so rather than guessing

Reference: https://togglefleet.com/docs