Quick Start Guide

Run Superposition

The quickest way to get started with superposition is to run the container image. This will run and expose superposition on port 8080.

Docker

docker run -p 8080:8080 ghcr.io/juspay/superposition-demo:latest

Podman

podman run -p 8080:8080 ghcr.io/juspay/superposition-demo:latest

Once the container image has started - you can play around with superposition at http://localhost:8080.

warning

The image ghcr.io/juspay/superposition-demo:latest is a demo image that contains a pre-populated set of organisations, workspaces and configurations. It is not meant for production use. To deploy Superposition in production, use the image ghcr.io/juspay/superposition:latest.

Openfeature Provider

Superposition supports OpenFeature, a standard for feature flagging. To use Superposition as an OpenFeature provider, you need to install the OpenFeature SDK for your language of choice and configure it to use Superposition as the provider.

Setup

Install the provider for your language of choice. The provider will allow you to read feature flags and configurations from Superposition.

Java

app/build.gradle

implementation "dev.openfeature:sdk:1.15.1"
implementation "io.juspay.superposition:openfeature-provider:0.87.0"

Kotlin

app/build.gradle.kts

implementation("dev.openfeature:sdk:1.15.1")
implementation("io.juspay.superposition:openfeature-provider:0.87.0")

Python

pip install openfeature-sdk
pip install superposition-provider

JavaScript

npm install superposition-provider

Rust

Cargo.toml

[dependencies]
open-feature = "0.2"
superposition_provider = "0.85.0"

Initialize and configure the Provider

Java

App.java

import dev.openfeature.sdk.*;
import io.juspay.superposition.openfeature.*;
import io.juspay.superposition.openfeature.options.RefreshStrategy;

import java.util.List;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        // Configure experimentation options
        SuperpositionProviderOptions.ExperimentationOptions expOptions =
            SuperpositionProviderOptions.ExperimentationOptions.builder()
                .refreshStrategy(RefreshStrategy.Polling.of(5000, 2000)) // 5s timeout, 2s interval
                .build();

        // Configure provider options
        SuperpositionProviderOptions options =
            SuperpositionProviderOptions.builder()
                .orgId("localorg")
                .workspaceId("test")
                .endpoint("http://localhost:8080")
                .token("api-token")
                .refreshStrategy(RefreshStrategy.Polling.of(10000, 5000)) // 10s timeout, 5s interval
                .experimentationOptions(expOptions)
                .build();

        // Initialize provider
        SuperpositionOpenFeatureProvider provider =
            new SuperpositionOpenFeatureProvider(options);
        EvaluationContext initCtx =
            new ImmutableContext(Map.of("foo", new Value("bar")));
        provider.initialize(initCtx);
  }
}

Kotlin

app/build.gradle.kts

package org.example

import dev.openfeature.sdk.*
import io.juspay.superposition.openfeature.*
import io.juspay.superposition.openfeature.options.RefreshStrategy

import io.juspay.superposition.sdk.*

fun main() {
    val spOptions = SuperpositionProviderOptions.builder()
        .orgId("localorg")
        .workspaceId("test")
        .endpoint("http://localhost:8080")
        .token("api-token")
        .refreshStrategy(RefreshStrategy.Polling.of(10000, 5000))
        .build()

    val provider = SuperpositionOpenFeatureProvider(spOptions)
    val initCtx = ImmutableContext(mapOf("foo" to Value("bar")))
    provider.initialize(initCtx)
    OpenFeatureAPI.getInstance().setProvider(provider)
}

Python

configuration.py

from openfeature import api
from superposition_provider.provider import SuperpositionProvider
from superposition_provider.types import ExperimentationOptions, SuperpositionProviderOptions, PollingStrategy

config_options = SuperpositionProviderOptions(
  endpoint="http://localhost:8080",
  token="api-token",
  org_id="localorg",
  workspace_id="test",
  refresh_strategy=PollingStrategy(
      interval=5,  # Poll every 5 seconds
      timeout=3    # Timeout after 3 seconds
  ),
  fallback_config=None,
  evaluation_cache_options=None,
  experimentation_options=ExperimentationOptions(
      refresh_strategy=PollingStrategy(
          interval=5,  # Poll every 5 seconds
          timeout=3    # Timeout after 3 seconds
      )
  )
)

provider = SuperpositionProvider(provider_options=config_options)
# Initialize provider
await provider.initialize(context=ctx)
api.set_provider(provider)

JavaScript

index.js

  import { OpenFeature } from '@openfeature/server-sdk';
  import { SuperpositionProvider } from 'superposition-provider';

  // create a simple configuration object, for all options check the provider documentation
  const config = {
    endpoint: "http://localhost:8080",
    token: "api-token",
    org_id: "localorg",
    workspace_id: "test",
  };
  const provider = new SuperpositionProvider(config);
  console.log("Provider created successfully");

  // Initialize the provider
  await OpenFeature.setProviderAndWait(provider);
  console.log("Provider initialized successfully");

Rust

main.rs

use superposition_provider::{
    ConfigurationOptions, SuperpositionOptions, SuperpositionProvider,
    SuperpositionProviderOptions, RefreshStrategy, PollingStrategy
};
use open_feature::OpenFeature;
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() {
    env_logger::init();

    // Get the OpenFeature API singleton
    let mut api = OpenFeature::singleton_mut().await;

    // Configure the Superposition provider
    let options = SuperpositionProviderOptions {

        endpoint: "http://localhost:8080/".to_string(),
        token: "api-token".to_string(),
        org_id: "localorg".to_string(),
        workspace_id: "test".to_string(),
        fallback_config: None,
        evaluation_cache: None,
        refresh_strategy: RefreshStrategy::Polling(PollingStrategy {
            interval: 60, // Poll every 60 seconds
            timeout: Some(30)
        }),
        experimentation_options: None // CAC only
    };

    // Set the provider
    api.set_provider(SuperpositionProvider::new(options)).await;
}

Evaluate Feature Flags

Once the provider is initialized, you can evaluate feature flags and configurations using the OpenFeature client.

Java

App.java

Client client = OpenFeatureAPI.getInstance().getClient();

// Create evaluation context (optional)
EvaluationContext ctx =
    new ImmutableContext(Map.of("userId", new Value("123")));

// Evaluate a boolean flag
boolean enabled = client.getBooleanValue("my-feature-flag", false, ctx);
System.out.println("Feature enabled: " + enabled);

// Evaluate & get the entire configuration
System.out.println("Full config: " + provider.evaluateConfig(ctx));

Kotlin

app/build.gradle.kts

val client = OpenFeatureAPI.getInstance().client
// Create evaluation context (optional)
val ctx = ImmutableContext(mapOf("d1" to Value(true)))

// Evaluate a boolean flag
val enabled = client.getBooleanValue("bool", false, ctx)
println("Feature enabled: $enabled")

// Evaluate & get the entire configuration
println("Full config: ${provider.evaluateConfig(ctx)}")

Python

configuration.py

client = api.get_client()

ctx = EvaluationContext(
  targeting_key="25",  # Using a targeting key for experiment variant decider
  attributes={'d1': 'd1'}
)

bool_val = client.get_boolean_details(
    flag_key="bool",
    default_value=True,
    evaluation_context=ctx
)
# Note: If you want the whole config, you can directly use the provider itself
resp = provider.resolve_all_config_details({}, ctx)
print(f"Response for all config: {resp}")

print("Successfully resolved boolean flag details:", bool_val)

JavaScript

index.js

const client = OpenFeature.getClient();
const context = {
  d1: "d1",
};

console.log("Testing feature flags...");

const boolValue = await client.getBooleanValue("bool", false, context);
console.log("Boolean flag 'bool':", boolValue);

const stringValue = await client.getStringValue(
  "string",
  "default",
  context,
);
console.log("String flag 'string':", stringValue);

const numberValue = await client.getNumberValue("number_key", 0, context);
console.log("Number flag 'number_key':", numberValue);

// Test resolving all config
const allConfig = await provider.resolveAllConfigDetails({}, context);
console.log("All config:", allConfig);

Rust

main.rs

// Create a client
let client = api.create_client();

// Wait for initialization
sleep(Duration::from_secs(3)).await;

// Evaluate feature flags
let int_value = client.get_int_value("my_feature_flag", None, None).await.unwrap();
println!("Feature flag value: {}", int_value);

Setup the SDK (Optional)

If you want to do more than just read configs, Superposition provides SDKs for various languages to interact with the platform. Any operation that can be performed via the UI can also be performed via the SDKs. Install the SDK for your language of choice to get started.

Java

app/build.gradle.kts

implementation("io.juspay.superposition:sdk:<version>")

Python

pip install superposition-sdk

JavaScript

npm install superposition-sdk

Rust

Cargo.toml

[dependencies]
superposition_sdk = "0.85.0"