Quickstart

Create a project, grab a publishable SDK key, install the SDK, and evaluate your first flag from Cloudflare's edge, every step here takes about five minutes end to end.

1. Create a project

In the dashboard, create a project. Every project ships with three environments out of the box, dev, staging, and prod. You don't configure them; they exist the moment the project does.

2. Grab an SDK key

Open the environment you want to wire up (start with dev) and create a publishable SDK key from the dashboard's Keys page. Copy the full key when it is shown, it looks like sos_sdk_... and is displayed exactly once. You cannot retrieve it again over the API.

An sos_sdk_* key is scoped to exactly one project and one environment, does edge evaluation only, and is safe to ship in a browser bundle. It can't write flags, only read them. See Concepts for the full key model.

3. Install the SDK

npm i @shipos/sdk

Building a React app? Add @shipos/react for hooks and a provider. The core @shipos/sdk runs in Node and the browser.

4. Create a flag

Create a flag from the dashboard or hand it to an agent. A new flag starts OFF at 0% in every environment, nothing is served until you enable it. That's deliberate: you ship the code dark, then turn it on once it's deployed.

You: create a boolean flag "checkout-v2" for the new checkout flow

Claude → create_flag { key: "checkout-v2", description: "New checkout flow" }
  ✅ Created flag "checkout-v2" (boolean) in project "shop".
     All environments start OFF at 0%, toggle_flag turns it on.

5. Wrap your code

Create a client with your SDK key and evaluate the flag. Every evaluation takes a default, so it never throws and never blocks, offline, on a typo, or during an outage you get your default back.

import { createClient } from "@shipos/sdk";

const shipos = createClient({ key: "sos_sdk_..." });

const useV2 = await shipos.flag("checkout-v2", {
  userId: "u_42",
  attributes: { plan: "pro", region: "eu" },
  default: false,
});

if (useV2) {
  renderNewCheckout();
} else {
  renderLegacyCheckout();
}

Deploy this. The flag is still OFF, so every user gets false , the legacy path. Your code is live but dark.

6. Turn it on and ramp

With the code deployed behind the flag, enable it and ramp the rollout. Raising the percentage only adds users, it never reshuffles who's already in (see Rollouts).

Claude → toggle_flag  { key: "checkout-v2", env: "prod", enabled: true }
  ✅ checkout-v2 @ prod → ON

Claude → set_rollout  { key: "checkout-v2", env: "prod", percent: 10 }
  ✅ checkout-v2 @ prod → 10% rollout

Next steps