Model Keys Edge

Concepts

ShipOS does one thing: feature flags. The model is small on purpose, a handful of nouns, three kinds of key, and one edge that serves every evaluation. This page defines them.

Orgs, projects, environments

An org is your account and billing boundary. Inside it you create projects, usually one per application or service. Every project starts with three environments: dev, staging, and prod.

Environments are the unit of isolation. A flag exists across all three, but its configuration, enabled, rollout percentage, targeting rules, served values, killed state, is independent per environment. See Environments.

Flags

A flag is a named switch of one kind: boolean, string, number, or json. Every flag has a defaultValue, the value served when the flag is missing or archived, and, in each environment, a config: enabled, rolloutPct, targeting rules, valueOn / valueOff, and a killed state.

Each environment's config carries a version for optimistic concurrency. Write to it with a PUT that includes expectedVersion; if the stored version has moved on you get a 409 version_conflict instead of a silent overwrite. See Feature Flags.

Keys

Three key prefixes, each with a different blast radius. Dashboard users authenticate with a session cookie; everything programmatic uses a key. Create and revoke keys in the dashboard, the full secret is shown once at creation and cannot be read back over the REST API.

Prefix	Works on	Can mutate?	Notes
`sos_sdk_*`	Edge evaluation only	No (read-only)	Publishable. Scoped to one project + environment. Safe in browsers.
`sos_agt_*`	MCP + control-plane API	Yes, directly	Agent key. Audited as an agent by its prefix.
`sos_adm_*`	Control-plane API + MCP	Yes, directly	Admin key. Full write access.

Ship the right key

Only sos_sdk_* keys belong in client code. Agent and admin keys can write and kill flags, keep them server-side and out of source control.

The edge

You author flags in the control plane, which persists to Postgres and pushes a compiled snapshot to Cloudflare KV. The edge evaluates flags directly from KV, so evaluation never touches a database and returns in under 50ms globally.

Two edge endpoints matter:

POST edge.shipos.app/v1/evaluate, evaluate one flag for a context. This is what the SDK calls.
GET edge.shipos.app/v1/snapshot, the full compiled config for a project + environment. The SDK background-polls this with If-None-Match; a 304 is nearly free.

text

author (dashboard · REST API · MCP)
        │
        ▼
  control plane  ──►  Postgres        (source of truth, versioned)
        │
        ▼
  Cloudflare KV  ──►  edge /v1/evaluate  ──►  @shipos/sdk  (<50ms)

Audit trail

Every write, create, toggle, rollout, targeting change, kill, promote - is appended to an immutable audit trail. Actions taken with an sos_agt_* key are attributed to the agent by key prefix, so you can always tell what a human did versus what an agent did. Pull it via the MCP tool get_audit_log.

Three ways in

Surface	Base	Auth	Best for
Dashboard	`app.shipos.app`	Session cookie	Observing state, one-off changes
REST API	`app.shipos.app/api/v1`	`sos_agt_` / `sos_adm_`	CI, scripts, automation
MCP server	`mcp.shipos.app/mcp`	`sos_agt_` / `sos_adm_`	Coding agents (Claude Code, Cursor)

The three surfaces have parity, the dashboard is the observation layer, not the only way in. See MCP Server for the full tool list.