juspay/superposition

Superposition

Quick start · Concepts · Self-hosting & setup · Architecture guide

Superposition is an open source configuration management platform that simplifies and enables safe, reliable configuration for applications.

Superposition helps teams manage configuration and experimentation in a smarter way. Instead of hardcoding values or juggling between messy config files, it lets you define defaults, set contexts/overrides (Rules) for different dimensions (like per-environment, tenant, region, or device), and safely roll out changes through experiments.

Think of it as a system where your configuration is aware of context: the right settings automatically apply to the right situation, with full type safety and controlled rollouts. Feature flags are just one thing you can do with it, not the main idea.

If you want to see it working first, start with the local demo below. If you want to understand the model before you run it, jump straight to the docs or architecture wiki.

Start in minutes

The fastest way to try Superposition locally is to run the demo image with a preloaded setup:

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

Then open http://localhost:8080 and explore the admin interface.

If you want to run the repository itself instead of the demo image:

git clone https://github.com/juspay/superposition.git
cd superposition
# Optional: enter the Nix dev shell if you use Nix
nix develop

# Start local dependencies (Postgres/Redis)
podman compose up -d

# Set up the dev environment and run Superposition
make setup
make run

docker compose up -d only starts local dependencies from docker-compose.yaml; it does not start the Superposition UI/API on :8080. Use make run to launch the server after setup.

If you are not using Nix, follow the dependency installation steps in the setup guide before running make setup.

Need the guided path? Start with the quick start guide or read the setup docs.

Why should you use Superposition

• Safety: use typed values, schema checks, validation functions, staggered rollouts, and versioned configs that you can revert to.
• Reliability: change configurations through experiments, overrides, and controlled promotion flows instead of shipping every change through application deploys.
• Easier management: use cascading configuration to avoid duplicating overrides for every variation across environment, tenant, region, device, or other dimensions.
• Auditability: see who changed what, when it changed, why it changed, and the description attached to the change.
• Integrations: connect through OpenFeature-compatible providers, SDKs, APIs, webhooks, and client libraries.

Superposition treats configuration like product logic, not scattered environment variables, one-off switch statements, or oversized feature flag trees. Read more about context-aware configuration and experimentation.

What you can build with it

Superposition fits anywhere you need configuration to change safely without redeploying application code.

• Frontend experiences with dynamic behavior, staged rollouts, and context-aware UI variants.
• Backend services with tenant-aware, region-aware, or policy-aware configuration.
• Payments and fintech decisioning such as routing, retry ladders, fee logic, or risk thresholds.
• LLM and AI application configuration where model, prompt, temperature, or retrieval behavior changes by context.
• Infrastructure control paths such as staggered releasers and operational toggles.
• Storage and platform layers that need centrally managed dynamic behavior.

Examples in this repository:

• Dynamic payment fields
• K8s staggered releaser
• CAC Redis module

Prefer examples over theory? Browse the examples directory and then wire in a client.

Why this is different from a feature flag service

Most feature flag systems start with booleans and add targeting on top. Superposition starts with context-aware configuration and treats feature flags as one outcome of that model.

That means you can:

• define typed default values,
• resolve them against rich multi-dimensional context,
• override them with predictable specificity,
• and run controlled experiments on top of those values.

If you are comparing tools, that is the lens to use: Superposition is best understood as context-aware configuration first, with feature flags and experimentation built on top.

Clients and providers

Superposition ships two integration surfaces:

1. SDK: use this to interact with the control plane and automate configuration and experimentation workflows.
2. Provider: use this OpenFeature-compatible client in applications that need to consume configuration and experiment assignments.

Language	SDK	Provider
Rust
JavaScript
Python
Java
Haskell
Go	TBD	TBD

Ready to integrate? Use the quick start guide and choose the SDK or provider that matches your application.

Key capabilities

• Admin UI for managing configurations, contexts, dimensions, experiments, and webhooks.
• Rich API support so every major workflow can be automated outside the UI.
• Safe configuration changes through validation, auditability, and experiment-driven rollout.
• Typed values and custom validators for stronger guarantees at change time.
• Multi-tenant isolation so multiple organizations and workspaces can coexist safely.
• Authentication and authorization controls to keep operational changes governed.

Want a broader systems view? Open the DeepWiki architecture guide.

Learn more

• Quick start
• Development setup
• Context-aware configuration concepts
• Experimentation concepts
• Context7 LLM-friendly docs
• DeepWiki repository guide

Metrics & observability

The HTTP API exposes Prometheus metrics on SUPERPOSITION_METRICS_PORT (default 9091):

curl http://localhost:9091/metrics

Contributing

We welcome contributions across the platform, clients, docs, and examples.

Start with the development setup docs. If you'd like help getting started, join the Discord community or email [email protected].

License

This repository is distributed under the Apache 2.0 license.

See the LICENSE file for the full terms and repository-specific details.