initFireweave / Init / Fireweave.init is the composition root. It validates mode, constructs one adapter, wraps it in a runtime, and returns a client. The client exposes controlPoints and registerTarget. Nothing downstream branches on mode again.
Web types are the browser package (
@fireweaveai/web-sdk). Server packages use the non-Web names. Go’s runtime type is fireweave.Runtime; its entry point is fireweave.Init.
Older architecture sketches show
FireweaveProvider, phc_ keys, exposurePolicy.defaultSend: true, and adapter("posthog") construction. Those are stale. Production credentials are a Fireweave project key (project-api-key_…) or a browser fw_public_… key. Construct a concrete adapter, or let initFireweave do it.Adapters
Remote adapters authenticate with
Authorization: Bearer <key>. The SDK reads no environment. Pass apiUrl and apiKey.
https is required off-loopback; http is loopback-only. Default allowlists name Fireweave hosts + loopback. Java’s list also still carries leftover PostHog hostnames — not a live vendor integration.
Never send PostHog phc_ / phs_ / phx_ keys on the Fireweave remote path. The web adapter rejects those shapes.
Evaluation path
- The client supplies
flagKey, expected type, default, and context (targetingKey+ attributes). - The runtime validates key, default-vs-type, context, then lifecycle — before any I/O.
- Not ready or already closed → default +
NotReady/AlreadyClosed. - The adapter evaluates. Remote:
POST /v1/flags/evaluate(side-effect-free). - The runtime coerces the typed value or returns
TypeMismatch+ default. - A Decision is built (
flagKey,value,variant,reason, error fields, metadata).
initFireweave / identify / setContext prefetch asynchronously. A prefetch that exceeds DEFAULT_FLAGS_READY_TIMEOUT_MS (5000) leaves the runtime STALE.
Lifecycle states
Verified states:UNINITIALIZED | INITIALIZING | READY | STALE | ERROR | FATAL | SHUTDOWN.
Default shutdown timeout is 10_000 ms. See Lifecycle.
Wire protocol
Spec version0.1.0. Paths implemented by remote adapters:
Auth on the wire:
Authorization: Bearer <key>. The spec also accepts x-api-key; shipped adapters send Bearer.
Evaluate request fields include targetingKey, attributes, groups, groupProperties, flagKeys. Register body: targetingKey, kind, environment, properties.
The test-server stub implements evaluate, capture, and /health. It does not implement /v1/targets/register.
There is no customer OpenAPI artifact in this docs repo. See HTTP API if that page is present.
Packages
See Compatibility and Package index.