Each SDK instance in CloudBees Unify is initialized with a single SDK key that binds it to a specific application and environment. This page explains why you might run multiple SDK instances in one application, how isolation between instances works, and what trade-offs to consider.
What multiple SDK keys enable
By default, an application uses one SDK key tied to one environment. Running multiple SDK instances lets a single application evaluate flags across more than one environment or context simultaneously, without redeploying or switching keys at runtime.
This capability is most useful in three situations:
Multi-tenant isolation is when different tenants or customers should evaluate flags against separate environments, so that targeting rules, flag values, and rollout percentages remain independent per tenant. A single application instance can route each request to the SDK instance for the appropriate tenant environment.
Regional isolation is when your application serves multiple regions with distinct flag configurations. Each region evaluates against its own environment, maintaining independent rollout control.
Cross-team flag sets is when multiple teams own separate applications with separate flag namespaces, but a single service needs to evaluate flags from both. Each team retains ownership and RBAC control over their application; the service loads both SDK instances.
How isolation works
Each SDK instance maintains its own cache, network connections, polling behavior, callbacks, and telemetry independently. This isolation is deliberate. If instances shared state, routing a request to the correct environment would be unreliable. Flag values intended for one tenant could bleed into another.
Each instance follows its own lifecycle: it initializes with its SDK key, fetches the current flag configuration, streams updates, and shuts down independently of other instances. This means a network error or stale configuration in one instance does not affect the others.
The legacy singleton and static API remain fully functional alongside instance-based clients. You can introduce multiple SDK keys incrementally, running the singleton for existing functionality while adding instance-based clients for new use cases.
Context switching between instances
The application is responsible for selecting which SDK instance to use for each request, user, or tenant. Once an instance is selected, it evaluates flags using the configuration for its bound environment and applies flag updates automatically as they stream in.
For accurate targeting, pass a consistent user or context object to each instance. If the same user is evaluated against different instances with different context objects, their flag evaluations may not match expectations. For example, a percentage rollout could place the user in different groups depending on which instance is called.
Trade-offs and operational considerations
Running multiple SDK instances increases resource use proportionally. Each instance maintains independent network connections and polling cycles, so high numbers of active instances will generate correspondingly higher network activity. If you are running more instances than necessary, consider consolidating environments or adjusting polling and streaming settings per instance.
When working with multiple instances, always use instance-scoped APIs rather than static custom property methods. Static methods apply globally and do not respect instance boundaries, which can cause custom properties set for one tenant to appear in evaluations for another.
For the steps to initialize and configure multiple SDK instances in your application, refer to Configure multiple SDK keys.