Environments Promote

Environments

Environments are how a flag moves from safe to real. Every project starts with three, dev, staging, and prod, and each carries its own independent config for every flag.

The three environments

Each project ships with dev, staging, and prod from the moment it's created. You don't provision them and you don't remove them, they are the fixed pipeline every flag flows through.

Independent per-env config

A flag exists across all three environments, but its config is separate in each: enabled, rolloutPct, targeting rules, valueOn / valueOff, killed state, and the config version. A flag can be ON at 100% in staging and OFF at 0% in prod at the same time, that's the point.

An sos_sdk_* key is bound to one environment, so the SDK in each environment only ever sees that environment's config. See Concepts.

Promoting a config

Once a flag's config is right in one environment, promote the whole config into another, for example staging → prod. Promotion copies the full env config (enabled, rollout, rules, values) from the source into the target.

http

POST https://app.shipos.app/api/v1/flags/{id}/environments/prod/promote
Authorization: Bearer sos_agt_...
Content-Type: application/json

{ "fromEnv": "staging" }

text

Claude → promote_config { key: "checkout-v2", toEnv: "prod", fromEnv: "staging" }
  ✅ checkout-v2: staging config promoted → prod

Promote is a deploy, it overwrites

Promoting replaces the entire destination config with the source, and it applies immediately (agent keys and admin keys alike execute directly). Every promote is audited by actor, and the flag's kill switch is always one call away if a prod promote goes wrong.

A typical flow

dev, build behind the flag, toggle freely, break things.
staging, set the targeting and rollout you intend to ship; verify against staging traffic.
prod, promote the staging config, then ramp with a rollout. Keep the kill switch one call away.