Unleash Cheat Sheet

Overview

Unleash is an open-source feature management platform that provides a robust system for feature toggles, gradual rollouts, and A/B testing. It supports multiple activation strategies out of the box including gradual rollout by user ID, IP-based targeting, application hostname targeting, and custom strategies. Unleash’s architecture separates the feature configuration (stored server-side) from the evaluation (performed client-side via SDKs), enabling fast local evaluation with minimal network overhead.

Unleash follows a privacy-first design where user data never leaves the application — all flag evaluation happens locally in the SDK using strategy definitions fetched from the server. The platform supports environments (development, staging, production), project-based organization, and comprehensive audit logging. With the Unleash Edge proxy for high-scale deployments and over 30 official SDKs, it scales from small startups to enterprise deployments handling billions of flag evaluations per day.

Installation

Self-Hosted via Docker

# Quick start with Docker
docker run -d \
  --name unleash \
  -p 4242:4242 \
  -e DATABASE_URL="postgres://unleash:password@host.docker.internal:5432/unleash" \
  -e DATABASE_SSL=false \
  -e INIT_ADMIN_API_TOKENS="*:*.unleash-admin-token" \
  unleashorg/unleash-server:latest

# Docker Compose setup
cat > docker-compose.yml << 'EOF'
version: "3.8"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: unleash
      POSTGRES_USER: unleash
      POSTGRES_PASSWORD: unleash_password
    volumes:
      - pgdata:/var/lib/postgresql/data

  unleash:
    image: unleashorg/unleash-server:latest
    ports:
      - "4242:4242"
    environment:
      DATABASE_URL: "postgres://unleash:unleash_password@postgres:5432/unleash"
      DATABASE_SSL: "false"
      INIT_ADMIN_API_TOKENS: "*:*.my-admin-token"
      INIT_CLIENT_API_TOKENS: "default:development.my-client-token"
    depends_on:
      - postgres

volumes:
  pgdata:
EOF

docker compose up -d
# Dashboard: http://localhost:4242

Kubernetes via Helm

# Add Unleash Helm repo
helm repo add unleash https://docs.getunleash.io/helm-charts
helm repo update

# Install Unleash
helm install unleash unleash/unleash \
  --namespace unleash \
  --create-namespace \
  --set postgresql.enabled=true \
  --set unleash.apiTokens.admin="*:*.admin-token" \
  --set unleash.apiTokens.client="default:development.client-token"

kubectl get pods -n unleash

SDK Installation

# Node.js
npm install unleash-client

# Python
pip install UnleashClient

# Go
go get github.com/Unleash/unleash-client-go/v4

# Java
# Maven: io.getunleash:unleash-client-java:9.0.0

# .NET
dotnet add package Unleash.Client

# Ruby
gem install unleash

# Rust
cargo add unleash-api-client

Core Commands — API Management

Feature Toggle Management

# Set API credentials
export UNLEASH_API="http://localhost:4242/api"
export UNLEASH_TOKEN="*:*.my-admin-token"

# Create a feature toggle
curl -X POST "$UNLEASH_API/admin/projects/default/features" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-payment-flow",
    "description": "Redesigned payment processing flow",
    "type": "release",
    "impressionData": true
  }'

# Enable toggle in an environment
curl -X POST "$UNLEASH_API/admin/projects/default/features/new-payment-flow/environments/development/on" \
  -H "Authorization: $UNLEASH_TOKEN"

# Disable toggle
curl -X POST "$UNLEASH_API/admin/projects/default/features/new-payment-flow/environments/development/off" \
  -H "Authorization: $UNLEASH_TOKEN"

# List all feature toggles
curl -s "$UNLEASH_API/admin/projects/default/features" \
  -H "Authorization: $UNLEASH_TOKEN" | jq '.features[] | {name, type, enabled: .environments[0].enabled}'

# Archive (soft delete) a toggle
curl -X DELETE "$UNLEASH_API/admin/projects/default/features/new-payment-flow" \
  -H "Authorization: $UNLEASH_TOKEN"

# Get toggle details
curl -s "$UNLEASH_API/admin/projects/default/features/new-payment-flow" \
  -H "Authorization: $UNLEASH_TOKEN" | jq '{name, type, environments}'

Activation Strategies

# Add gradual rollout strategy (percentage-based)
curl -X POST "$UNLEASH_API/admin/projects/default/features/new-payment-flow/environments/production/strategies" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "flexibleRollout",
    "parameters": {
      "rollout": "25",
      "stickiness": "userId",
      "groupId": "new-payment-flow"
    },
    "constraints": []
  }'

# Add user ID targeting strategy
curl -X POST "$UNLEASH_API/admin/projects/default/features/new-payment-flow/environments/production/strategies" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "userWithId",
    "parameters": {
      "userIds": "user-1,user-2,user-3"
    }
  }'

# Add strategy with constraints
curl -X POST "$UNLEASH_API/admin/projects/default/features/new-payment-flow/environments/production/strategies" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "flexibleRollout",
    "parameters": {
      "rollout": "100",
      "stickiness": "default",
      "groupId": "new-payment-flow"
    },
    "constraints": [
      {
        "contextName": "country",
        "operator": "IN",
        "values": ["US", "CA", "UK"]
      },
      {
        "contextName": "plan",
        "operator": "STR_EQUALS",
        "value": "enterprise"
      }
    ]
  }'

Core Commands — SDK Usage

Node.js SDK

const { initialize, isEnabled } = require('unleash-client');

const unleash = initialize({
  url: 'http://localhost:4242/api/',
  appName: 'my-app',
  customHeaders: {
    Authorization: 'default:development.client-token',
  },
  refreshInterval: 15000,  // ms
  metricsInterval: 60000,  // ms
});

unleash.on('ready', () => {
  // Simple boolean check
  const enabled = isEnabled('new-payment-flow');
  
  // Check with context (user targeting)
  const context = {
    userId: 'user-123',
    properties: {
      plan: 'enterprise',
      country: 'US',
    },
  };
  
  const userEnabled = isEnabled('new-payment-flow', context);
  
  // Get variant (A/B testing)
  const variant = unleash.getVariant('new-payment-flow', context);
  console.log(`Variant: ${variant.name}, Payload: ${variant.payload?.value}`);
});

unleash.on('error', console.error);

// Graceful shutdown
process.on('SIGTERM', () => unleash.destroy());

Python SDK

from UnleashClient import UnleashClient

client = UnleashClient(
    url="http://localhost:4242/api/",
    app_name="my-python-app",
    custom_headers={"Authorization": "default:development.client-token"},
    refresh_interval=15,
    metrics_interval=60,
)

client.initialize_client()

# Simple check
if client.is_enabled("new-payment-flow"):
    print("New payment flow active")

# Check with context
context = {
    "userId": "user-123",
    "properties": {
        "plan": "enterprise",
        "country": "US",
    },
}

if client.is_enabled("new-payment-flow", context):
    print("Enabled for this user")

# Get variant
variant = client.get_variant("new-payment-flow", context)
print(f"Variant: {variant['name']}")

# Cleanup
client.destroy()

Configuration

Variants (A/B Testing)

# Add variants to a feature toggle
curl -X PATCH "$UNLEASH_API/admin/projects/default/features/new-payment-flow/environments/production/variants" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "control",
      "weight": 334,
      "weightType": "fix",
      "stickiness": "userId",
      "payload": {"type": "json", "value": "{\"theme\": \"classic\"}"}
    },
    {
      "name": "variant-a",
      "weight": 333,
      "weightType": "fix",
      "stickiness": "userId",
      "payload": {"type": "json", "value": "{\"theme\": \"modern\"}"}
    },
    {
      "name": "variant-b",
      "weight": 333,
      "weightType": "fix",
      "stickiness": "userId",
      "payload": {"type": "json", "value": "{\"theme\": \"minimal\"}"}
    }
  ]'

Segments

# Create a reusable segment
curl -X POST "$UNLEASH_API/admin/segments" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beta Testers",
    "description": "Users opted into beta program",
    "constraints": [
      {
        "contextName": "beta",
        "operator": "STR_EQUALS",
        "value": "true"
      }
    ]
  }'

# Apply segment to a strategy
curl -X PUT "$UNLEASH_API/admin/projects/default/features/new-payment-flow/environments/production/strategies/STRATEGY_ID" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "flexibleRollout",
    "parameters": {"rollout": "100", "stickiness": "default", "groupId": "beta"},
    "segments": [SEGMENT_ID]
  }'

Unleash Edge (High-Performance Proxy)

# Run Unleash Edge
docker run -d \
  --name unleash-edge \
  -p 3063:3063 \
  -e UPSTREAM_URL="http://unleash:4242" \
  -e TOKENS="default:production.client-token" \
  unleashorg/unleash-edge:latest

# Edge with custom configuration
docker run -d \
  --name unleash-edge \
  -p 3063:3063 \
  -e UPSTREAM_URL="http://unleash:4242" \
  -e TOKENS="*:production.client-token" \
  -e REFRESH_INTERVAL_SECS=5 \
  -e METRICS_INTERVAL_SECS=30 \
  -e LOG_LEVEL=info \
  unleashorg/unleash-edge:latest

# Point SDKs to Edge instead of Unleash server
# url: 'http://localhost:3063/api/'

Advanced Usage

Custom Strategies

# Register a custom strategy (server-side)
curl -X POST "$UNLEASH_API/admin/strategies" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tenantRollout",
    "description": "Roll out to specific tenants",
    "parameters": [
      {"name": "tenantIds", "type": "list", "description": "Comma-separated tenant IDs", "required": true}
    ]
  }'

# Use custom strategy on a toggle
curl -X POST "$UNLEASH_API/admin/projects/default/features/new-payment-flow/environments/production/strategies" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tenantRollout",
    "parameters": {"tenantIds": "tenant-1,tenant-2,tenant-3"}
  }'

Projects and Environments

# Create a project
curl -X POST "$UNLEASH_API/admin/projects" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "payments",
    "name": "Payments",
    "description": "Payment service feature flags"
  }'

# Create an environment
curl -X POST "$UNLEASH_API/admin/environments" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "canary",
    "type": "production",
    "sortOrder": 150
  }'

# Connect environment to project
curl -X POST "$UNLEASH_API/admin/projects/payments/environments" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "canary"}'

API Tokens and Access

# Create a client API token
curl -X POST "$UNLEASH_API/admin/api-tokens" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenName": "production-client",
    "type": "client",
    "environment": "production",
    "projects": ["payments"]
  }'

# Create a frontend (browser) token
curl -X POST "$UNLEASH_API/admin/api-tokens" \
  -H "Authorization: $UNLEASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenName": "web-frontend",
    "type": "frontend",
    "environment": "production",
    "projects": ["default"]
  }'

# List all API tokens
curl -s "$UNLEASH_API/admin/api-tokens" \
  -H "Authorization: $UNLEASH_TOKEN" | jq '.tokens[] | {tokenName, type, environment, project}'

Troubleshooting

Issue	Cause	Solution
Toggle always returns false	Strategy not added or environment disabled	Add an activation strategy and enable the environment
SDK not receiving updates	Refresh interval too high	Reduce refreshInterval or use Unleash Edge
Gradual rollout uneven	Stickiness field not unique	Use userId stickiness with unique user identifiers
Custom strategy ignored	Strategy not registered server-side	Register strategy via API before using in toggles
Variant weights not matching	Weights don’t sum to 1000	Ensure all variant weights sum to exactly 1000
Edge proxy stale data	Token scope too narrow	Ensure Edge token has access to all required projects
Database migrations failing	PostgreSQL version mismatch	Use PostgreSQL 13+ for compatibility
Metrics not showing	metricsInterval set to 0	Set metricsInterval > 0 in SDK configuration

# Check Unleash health
curl http://localhost:4242/health

# Debug: get all client features (what SDKs see)
curl -s "http://localhost:4242/api/client/features" \
  -H "Authorization: default:development.client-token" | jq '.features | length'

# Check Edge health
curl http://localhost:3063/health

# View audit log
curl -s "$UNLEASH_API/admin/events?feature=new-payment-flow" \
  -H "Authorization: $UNLEASH_TOKEN" | jq '.events[] | {type, createdBy, createdAt}'

# Docker logs
docker logs unleash --tail=50