Licensing Your Instance

Every kuploy-cloud instance requires a valid license to operate. Without a license:

• Resource creation is blocked (projects, apps, databases, etc.)
• Deployments cannot be started
• The Setup Wizard is displayed to guide you through linking

Your license determines your plan limits and enables the instance to sync with the license hub.

Linking Your Instance

There are two ways to link your kuploy-cloud instance to a license:

Option A: Claim Code (Recommended)

The easiest way to link your instance - no configuration required:

1. Start your kuploy-cloud instance without any license configuration
2. A Setup Wizard will appear displaying a claim code (e.g., KPXY-4829)
3. Go to kuploy.app/claim and sign in
4. Enter the claim code and select which license to link
5. Your instance will automatically receive the license and begin syncing

Benefits:

• No manual .env editing required
• No need to copy/paste license keys
• Works behind firewalls (uses outbound polling)
• Secure: codes expire after 15 minutes

tip

The claim code appears on your kuploy-cloud instance screen. Just open kuploy.app/claim in another browser tab to complete the linking.

Option B: Manual Configuration

For automated deployments or when claim code isn't suitable, you can manually configure the license:

Add the following to your kuploy-cloud .env file:

LICENSE_KEY=lic_xxxxxxxxxxxxxxxx
LICENSE_HUB_URL=https://kuploy.app

Then restart your kuploy-cloud instance.

Important: Environment Variable Takes Priority

If LICENSE_KEY is set in your environment, it always takes priority over any previously claimed license stored in the database. The Setup Wizard will be skipped and your instance will use the environment variable directly.

To switch back to using a claimed license, remove the LICENSE_KEY environment variable and restart.

Finding Your License Key

1. Sign in to kuploy.app
2. Go to Licenses
3. Click on your license to view details
4. Copy the license key

License Sync

Once linked, your instance will:

• Validate the license on startup
• Sync usage data every 5 minutes (configurable)
• Cache limits locally for fast quota checks
• Report instance health and service stats

Sync Response

The license sync returns limits and feature flags that your instance should use to gate functionality:

{
  "valid": true,
  "limits": {
    "projects": 20,
    "apps": 50,
    "databases": 25,
    "domains": 50,
    "customDomains": 10,
    "freeSubdomains": 5,
    "teamMembers": 20,
    "buildMinutes": 2000,
    "storageBytes": 268435456000,
    "instances": 3
  },
  "features": {
    "whiteLabel": false,
    "customDomains": true,
    "domainPurchase": false
  },
  "aggregateUsage": { ... },
  "warnings": [],
  "billingPeriodReset": "2025-02-01T00:00:00Z",
  "gracePeriodHours": 24,
  "cacheExpiresAt": "2025-01-12T00:00:00Z"
}

Plan Features

Feature flags indicate what capabilities are available on your license:

Feature	Description
whiteLabel	Remove Kuploy branding from your instance
customDomains	End users can add their own custom domains
domainPurchase	End users can purchase domains through the platform

Use these flags to conditionally enable/disable features in your instance UI.

Domain Limits

The sync response includes domain-specific limits:

Limit	Description
domains	Total domain slots (legacy)
customDomains	User-provided custom domains allowed
freeSubdomains	Free *.kuploy.app subdomains allowed

Offline Behavior

If your instance can't reach the license hub:

1. Cached limits continue to work
2. Local quota enforcement remains active
3. Usage deltas are queued for next sync
4. A warning banner appears in the dashboard

When connection is restored, your instance will sync all pending usage data.

Troubleshooting

"License validation failed"

• Verify your license key is correct
• Check that LICENSE_HUB_URL points to https://kuploy.app
• Ensure your instance can reach the internet

"Claim code expired"

Claim codes expire after 15 minutes for security. Generate a new one by restarting the Setup Wizard or refreshing the setup page on your instance.

"Instance limit reached"

Your plan has a maximum number of instances. To add more:

• Upgrade your plan at kuploy.app/billing
• Or remove unused instances from your license

Environment Variables

Variable	Description	Default
LICENSE_KEY	Your license key	(none)
LICENSE_HUB_URL	License hub URL	https://kuploy.app
LICENSE_SYNC_INTERVAL_SECONDS	Sync interval	300 (5 min)
LICENSE_SYNC_RETRY_SECONDS	Retry on failure	60 (1 min)