Quickstart

This walkthrough goes Install → Initialize → Register target → Evaluate → Shutdown. Examples use local mode, so you do not need a network or a project key. Example keys match the SDK docs: new-checkout and user_42. The wire protocol still says flagKey. The product name is control point. Evaluation never throws — a failure returns your default. mode is required and never inferred. Remote without credentials is a boot error. The SDK never falls back to local.

Prerequisites

Node / Bun / Deno: Node.js >=20.20, or Bun >=1.2, or Deno >=2.0.
Python: Python >=3.10 and a virtualenv.
Go: Go 1.25.13 or later. The module path requires the /v2 suffix.
Java: JDK 11+.
Rust: Rust 1.75 or later.
Browser: A frontend toolchain. Use a fw_public_ key in production — see Configuration.

Offline steps need no Fireweave credentials. Production needs a project key and a fw-server base URL. Pass them as explicit init options. The SDK reads no environment variables.

Install

Packages published 2026-09-09 at 2.3.0.

Install @fireweaveai/server-sdk. Do not install @fireweaveai/sdk — that name is frozen at 2.1.0.

npm install @fireweaveai/server-sdk

Bun:

bun add @fireweaveai/server-sdk

Deno needs no install step:

import { initFireweave } from 'npm:@fireweaveai/server-sdk';

python -m venv .venv
.venv/bin/pip install fireweave

There is no [openfeature] or [posthog] extra. The only extra is dev (pytest).

The /v2 suffix is required in both go get and import paths.

go get github.com/FireWeave-HQ/fireweave-sdk/sdks/go/v2@v2.3.0

Maven Central, ai.fireweave:fireweave-sdk 2.3.0. fireweave-openfeature, fireweave-adapter-posthog, and fireweave-testing remain at 0.1.0 and are not this SDK.

<dependency>
  <groupId>ai.fireweave</groupId>
  <artifactId>fireweave-sdk</artifactId>
  <version>2.3.0</version>
</dependency>

cargo add fireweave

Or in Cargo.toml:

fireweave = "2.3.0"

npm install @fireweaveai/web-sdk

Initialize

Call the language entry point with mode: 'local' and a seeded map. Init fails loudly on bad configuration. Reads on the returned client never throw.

import { initFireweave } from '@fireweaveai/server-sdk';

const fireweave = await initFireweave({
  mode: 'local',
  local: { controlPoints: { 'new-checkout': true } },
});

from fireweave import init_fireweave

fireweave = init_fireweave(
    mode="local",
    local={"control_points": {"new-checkout": True}},
)

import "github.com/FireWeave-HQ/fireweave-sdk/sdks/go/v2/fireweave"

client, err := fireweave.Init(fireweave.Options{
    Mode: fireweave.ModeLocal,
    Local: &fireweave.LocalOptions{
        ControlPoints: map[string]bool{"new-checkout": true},
    },
})
if err != nil {
    panic(err)
}

Public control-point methods do not take context.Context. They use context.Background() internally.

Types live under ai.fireweave.sdk.application and ai.fireweave.sdk.domain — there is no facade re-export package.

import ai.fireweave.sdk.application.Fireweave;
import ai.fireweave.sdk.application.FireweaveClient;
import ai.fireweave.sdk.application.InitOptions;

import java.util.Map;

FireweaveClient fireweave = Fireweave.init(
    InitOptions.local(Map.of("new-checkout", true)));

use fireweave::{init_fireweave, InitOptions};
use std::collections::HashMap;

let mut control_points = HashMap::new();
control_points.insert("new-checkout".to_string(), true);
let fireweave = init_fireweave(
    InitOptions::local_with_control_points(control_points)
).unwrap();

import { initFireweave } from '@fireweaveai/web-sdk';

const fireweave = await initFireweave({
  mode: 'local',
  local: { controlPoints: { 'new-checkout': true } },
});

Reads after init are synchronous. If a remote prefetch exceeds 5 seconds, the runtime enters STALE and getters return defaults with reason STALE.

Register durable properties once per login. The call never throws. Check ok — a silently unregistered target is how targeting rules match nobody.In local mode the adapter records the target in-process, emits a [fireweave:local] trace line, and returns { ok: true }. Nothing is sent to fw-server.

const registered = await fireweave.registerTarget('user_42', {
  kind: 'user',
  properties: { plan: 'pro', region: 'eu-west' },
});
if (!registered.ok) {
  console.warn('registerTarget failed', registered.error);
}

from fireweave import RegisterTargetOptions

result = fireweave.register_target(
    "user_42",
    RegisterTargetOptions(kind="user", properties={"plan": "pro", "region": "eu-west"}),
)
if not result.ok:
    print("register_target failed", result.error)

registered := client.RegisterTarget("user_42", &fireweave.RegisterTargetOptions{
    Kind:       fireweave.TargetKindUser,
    Properties: map[string]any{"plan": "pro", "region": "eu-west"},
})
if !registered.OK {
    fmt.Println("registerTarget failed", registered.Error)
}

import ai.fireweave.sdk.application.RegisterTargetOptions;
import ai.fireweave.sdk.domain.JsonValue;
import ai.fireweave.sdk.domain.TargetKind;

var registered = fireweave.registerTarget("user_42",
    RegisterTargetOptions.builder()
        .kind(TargetKind.USER)
        .property("plan", JsonValue.of("pro"))
        .property("region", JsonValue.of("eu-west"))
        .build());
if (!registered.ok()) {
    System.out.println("registerTarget failed " + registered.error());
}

use fireweave::RegisterTargetOptions;

let properties = serde_json::json!({ "plan": "pro", "region": "eu-west" })
    .as_object()
    .unwrap()
    .clone();
let registered = fireweave.register_target(
    "user_42",
    Some(&RegisterTargetOptions {
        properties: Some(properties),
        ..Default::default()
    }),
);
if !registered.ok {
    eprintln!("register_target failed {:?}", registered.error);
}

const registered = await fireweave.identify('user_42', {
  kind: 'user',
  properties: { plan: 'pro', region: 'eu-west' },
});

identify calls registerTarget, then setContext({ targetingKey }) so the next prefetch buckets on that id. You can also call registerTarget directly.

Evaluate a control point

Pass a stable targetingKey. Do not invent an SDK helper named fw.isOn — that API does not exist.

const enabled = await fireweave.controlPoints.getBooleanValue('new-checkout', false, {
  targetingKey: 'user_42',
});
console.log('new-checkout:', enabled);

Detailed decision: fireweave.controlPoints.getBooleanDetails('new-checkout', false, { targetingKey: 'user_42' }).

from fireweave import EvaluationContext

enabled = fireweave.control_points.get_boolean_value(
    "new-checkout", False, EvaluationContext(targeting_key="user_42")
)
print("new-checkout:", enabled)

evalCtx := fireweave.NewEvaluationContext("user_42", nil)
enabled := client.ControlPoints().GetBooleanValue("new-checkout", false, &evalCtx)
fmt.Println("new-checkout:", enabled)

import ai.fireweave.sdk.domain.EvaluationContext;

boolean enabled = fireweave.controlPoints().getBooleanValue(
    "new-checkout",
    false,
    EvaluationContext.builder().targetingKey("user_42").build());
System.out.println("new-checkout: " + enabled);

use fireweave::EvaluationContext;

let ctx = EvaluationContext::new().with_targeting_key("user_42");
let enabled = fireweave.control_points.get_boolean_value(
    "new-checkout",
    false,
    Some(&ctx),
);
println!("new-checkout: {enabled}");

const enabled = fireweave.controlPoints.getBooleanValue('new-checkout', false, {
  targetingKey: 'user_42',
});
console.log('new-checkout:', enabled);

No await — web getters are synchronous cache reads.

A v1 read is side-effect free. It does not record exposures or emit telemetry because you called it.

Shut down

One runtime, one shutdown.

await fireweave.shutdown();

fireweave.shutdown()

Never raises; idempotent. You can also use with init_fireweave(...) as fireweave:.

shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
_ = client.Runtime().Shutdown(shutdownCtx)

fireweave.close();

fireweave.shutdown();

await fireweave.shutdown();

Production (remote mode)

Swap local mode for mode: 'remote' and pass apiUrl / apiKey (or the language equivalent) as explicit options. The SDK does not read FW_API_URL or FW_PROJECT_API_KEY. Your app may read those itself and pass them in. Auth is Authorization: Bearer <key>. Use a Fireweave project key (project-api-key_…), not a PostHog phc_ / phs_ / phx_ key. In the browser, use a fw_public_ key — see Configuration.

import { initFireweave } from '@fireweaveai/server-sdk';

const fireweave = await initFireweave({
  mode: 'remote',
  apiUrl: process.env.FW_API_URL,
  apiKey: process.env.FW_PROJECT_API_KEY,
});

https is required off-loopback; http is loopback-only.

from fireweave import init_fireweave
import os

fireweave = init_fireweave(
    mode="remote",
    api_url=os.environ["FW_API_URL"],
    api_key=os.environ["FW_PROJECT_API_KEY"],
)

client, err := fireweave.Init(fireweave.Options{
    Mode:   fireweave.ModeRemote,
    APIURL: os.Getenv("FW_API_URL"),
    APIKey: os.Getenv("FW_PROJECT_API_KEY"),
})
if err != nil {
    panic(err)
}

Java does not call System.getenv. Read env in your app and pass the values in.

FireweaveClient fireweave = Fireweave.init(
    InitOptions.remote(apiKey, apiUrl));

use fireweave::{init_fireweave, InitOptions};

let fireweave = init_fireweave(InitOptions::remote(
    std::env::var("FW_PROJECT_API_KEY").unwrap(),
    std::env::var("FW_API_URL").unwrap(),
)).unwrap();

apiUrl and apiKey are required. Use a fw_public_ key scoped to flags:evaluate and events:write. Do not embed a secret or attest:write project key in a browser bundle. See Configuration.

import { initFireweave } from '@fireweaveai/web-sdk';

const fireweave = await initFireweave({
  mode: 'remote',
  apiUrl,
  apiKey,
  context: { targetingKey: 'anonymous' },
});

Set the fw-server URL from your project. A self-hosted host must appear in allowedHosts, or pass ['*'] / language equivalent to opt out of the allowlist.

Next steps

Language surfaces: Node, Python, Go, Java, Browser, Rust, Compatibility
Concepts: Control points, Targeting, Adapters
Production: Configuration, Lifecycle, Errors
Tests without a network: Testing
If a getter always returns the default: Troubleshooting

Get Started

SDKs

Concepts

Production

CLI

Terraform

Testing

Troubleshooting

Migration

Reference

Prerequisites

Production (remote mode)

Next steps

​Prerequisites

​Production (remote mode)

​Next steps

Prerequisites

Production (remote mode)

Next steps