Skip to main content

Link your instance to a license

Every kuploy-cloud instance requires a valid license to operate. The license determines plan limits and authorises the instance to sync with the licensing hub at kuploy.app.

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

This page is the Kuploy Cloud setup. What licenses have in common across every product — claim codes, sync states, who operates a deployment, and why a key is a credential — is on Licenses.

Platform plans vs. instance plans

What you pay kuploy.app and what your organizations pay you are two separate layers — see Plans & the two layers.

Platform Plans​

Your Kuploy Cloud tier sets aggregate limits and feature flags across every instance linked to your license. The tiers, their limits and their features are on Plans & the two layers → Kuploy Cloud tiers; prices are on kuploy.app/pricing.

Other products​

Leeram Business and GrowthOps use the same licenses, but operator authority and setup differ. See Licenses → Who operates a deployment, Leeram Business and GrowthOps.

Linking Your Instance​

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

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 (Environment Variables)​

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

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.

Option C: Admin UI Configuration​

You can also configure (or update) the license hub connection directly from the admin dashboard — no restart required:

  1. Go to Admin → Domains → License Hub Integration
  2. Enter the License Hub URL and License Key
  3. Click Save License Hub Configuration

UI-saved configuration takes precedence over environment variables. This means you can bootstrap with env vars and later override them via the UI without needing to change your .env file or restart.

Configuration Precedence

The effective license configuration follows this order:

  1. Admin UI config (stored in DB) — highest priority when saved
  2. Environment variables (LICENSE_KEY, LICENSE_HUB_URL) — used as bootstrap/fallback
  3. Claim flow (license stored in DB from claim code) — used when no env vars set

To reset back to environment variables, use Admin → Domains → Reset License Hub.

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

Environment variables​

The license variables — LICENSE_KEY, LICENSE_HUB_URL and LICENSE_SYNC_INTERVAL_SECONDS — are listed in the Environment Variables Reference. A license hub configuration saved in the admin UI (Admin → Domains) takes precedence over them, with no restart.

Next​