Licensing & Platform Plans

Every kuploy-cloud instance requires a valid license to operate. Your license determines your platform plan limits and enables 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

Platform Plans vs. Instance Plans

This page covers platform plans — the subscription you (the tenant) pay to kuploy.app. These control what your kuploy-cloud instances can do.

For the plans your end users (organizations) subscribe to within your instance, see Cloud Billing Setup and Plans & Usage.

Platform Plans

For current pricing, see kuploy.app/pricing.

Plan	Description
Hobby	Perfect for testing and personal projects
Starter	For freelancers and small teams getting started
Growth	For growing businesses needing AI and multi-server
Business	For mid-size ISPs/ITSPs with priority support
Enterprise	For large resellers — custom pricing, white-label branding

Plan Limits

These limits are aggregate — they apply across all instances linked to your license.

Resource	Hobby	Starter	Growth	Business	Enterprise
Projects	1	5	20	50	Unlimited
Apps	2	15	50	150	Unlimited
Databases	1	5	25	75	Unlimited
Custom Domains	0	3	10	50	Unlimited
Free Subdomains	1	2	5	10	Unlimited
Purchasable Domains	0	0	0	0	Unlimited
Team Members	1	5	20	50	Unlimited
Build Minutes	100	500	2,000	5,000	10,000
Storage	5 GB	50 GB	250 GB	1 TB	2 TB
Instances	1	1	1	3	Unlimited

Feature Flags

Feature flags control which capabilities are available on your license:

Feature	Hobby	Starter	Growth	Business	Enterprise
Custom Domains	-	Yes	Yes	Yes	Yes
AI Assistant	-	-	Yes	Yes	Yes
Multi-Server	-	-	Yes	Yes	Yes
Priority Support	-	-	-	Yes	Yes
White-Label	-	-	-	-	Yes
Domain Purchase	-	-	-	-	Yes

Plan Details

Hobby (Free)

Perfect for learning and personal projects:

• Deploy a single project with up to 2 apps
• 100 build minutes per month
• 1 free subdomain (yourapp.kuploy.app)
• Community support

Starter

For freelancers and small teams getting started:

• 5 projects with up to 15 apps
• 500 build minutes per month
• 3 custom domains + 2 free subdomains
• Email support

Growth

For growing businesses:

• 20 projects with up to 50 apps
• 2,000 build minutes per month
• 10 custom domains + 5 free subdomains
• AI-powered deployment assistant
• Multi-server deployments
• Email support

Business

For mid-size ISPs and ITSPs:

• 50 projects with up to 150 apps
• 5,000 build minutes per month
• 50 custom domains + 10 free subdomains
• AI assistant + multi-server
• Priority support (faster response times)
• Up to 3 instances

Enterprise (Custom Pricing)

For large resellers with white-label branding. Enterprise pricing is negotiated per customer — there is no fixed monthly rate.

• Contact sales@kuploy.app or visit kuploy.app/pricing to discuss your needs
• Unlimited projects, apps, databases
• 10,000 build minutes per month
• Unlimited custom domains
• White-label branding (remove Kuploy branding)
• Domain purchase (buy domains through platform)
• All features included
• Unlimited instances

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 (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

Reassigning an Instance to a Different License

If you've created a new license (e.g., under a different email or after switching plans) and your existing kuploy-cloud instance is still connected to the old license, a platform admin can reassign the instance without any downtime or manual reconfiguration on your end.

What happens during reassignment:

1. The admin moves your instance to the new license in the kuploy.app dashboard
2. On the next sync cycle (within 5 minutes), your instance automatically detects the change
3. Your instance receives the new license key and begins using the new license's limits and features
4. No restart or .env changes are needed on your kuploy-cloud instance

When you might need this:

• You created a new license under a different email address
• Your old license expired and you purchased a new one
• You're consolidating multiple licenses

tip

If your instance is stuck on an expired or wrong license, contact your platform administrator or reach out to support@kuploy.app to request an instance reassignment.

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 uses to gate functionality:

{
  "valid": true,
  "limits": {
    "projects": 20,
    "apps": 50,
    "databases": 25,
    "domains": 50,
    "customDomains": 10,
    "freeSubdomains": 5,
    "purchasableDomains": 0,
    "teamMembers": 20,
    "buildMinutes": 2000,
    "storageBytes": 268435456000,
    "instances": 3
  },
  "features": {
    "whiteLabel": false,
    "customDomains": true,
    "domainPurchase": false,
    "aiAssistant": true,
    "multiServer": true,
    "prioritySupport": false
  },
  "aggregateUsage": {
    "projects": 12,
    "apps": 28,
    "databases": 8,
    "domains": 30,
    "customDomains": 6,
    "purchasedDomains": 0,
    "freeSubdomains": 3,
    "teamMembers": 10,
    "buildMinutes": 850,
    "storageBytes": 53687091200
  },
  "warnings": [],
  "billingPeriodReset": "2025-02-01T00:00:00Z",
  "gracePeriodHours": 24,
  "cacheExpiresAt": "2025-01-12T00:00:00Z"
}

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
purchasableDomains	Domains purchasable through the platform (Enterprise only)

Multi-Instance Aggregate Quotas

If your plan allows multiple instances (Business: 3, Enterprise: unlimited), usage is aggregated across all instances under the same license.

For example, with a Growth plan (20 project limit):

• Instance A has 8 projects
• Instance B has 5 projects
• Instance C has 3 projects
• Aggregate: 16/20 (80%) — a warning is triggered

Each instance receives the aggregate usage in its sync response, ensuring quota enforcement is consistent regardless of which instance a resource is created on.

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.

Cache State Machine

The license cache follows this state progression:

State	Description	Behavior
fresh	Valid license, cache within TTL	Full operation allowed
stale	Valid license, cache expired, in grace period	Operations allowed, warning banner shown
frozen	Grace period expired, cannot reach server	New resource creation blocked
empty	No license configured	Blocks creation if LICENSE_KEY expected
invalid	License validation failed	New resource creation blocked

Instance Reassignment

If you need to move an instance from one license to another — for example, after creating a new license under a different email — a platform admin can reassign it for you.

What Happens During Reassignment

1. The admin reassigns your instance to the target license via the admin dashboard
2. On the next sync cycle (within 5 minutes), your instance automatically receives the new license key
3. No restart or .env changes are needed on your end — it's seamless

tip

If your instance has LICENSE_KEY hardcoded in its .env, the sync will still work correctly. The hub detects the mismatch by instance ID and responds with the correct license data. However, you should update the .env to match the new key to avoid confusion.

Viewing Assignment History

You can see the full reassignment history for any license:

1. Sign in to kuploy.app
2. Go to Licenses
3. Click on a license to view its detail page
4. The Assignment History section shows all past reassignments, including timestamps and which license the instance moved from/to

This is useful for auditing when an instance was moved between licenses and tracking changes over time.

Managing Your Platform Subscription

Upgrading Your Plan

1. Sign in to kuploy.app
2. Go to Billing
3. Click Upgrade on your desired plan
4. Complete payment via Stripe
5. New limits apply immediately to all linked instances

note

When upgrading mid-cycle, you're charged a prorated amount for the remainder of the billing period.

Downgrading Your Plan

1. Go to Billing at kuploy.app
2. Click Manage Subscription
3. Select a lower plan
4. Downgrade takes effect at the end of your billing period

caution

Before downgrading, ensure your aggregate usage across all instances is within the new plan's limits. You may need to remove resources to fit within the lower limits.

Troubleshooting

"License validation failed"

• Verify your license key is correct
• Check that LICENSE_HUB_URL points to https://kuploy.app (or check Admin → Domains for the effective URL)
• If you configured the license via the admin UI, the UI values override env vars — verify the saved URL is correct
• 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

Instance stuck on old/expired license

If you created a new license but your instance is still reporting against an old one:

1. Contact your platform admin to reassign your instance to the new license
2. The reassignment takes effect on the next sync cycle (within 5 minutes)
3. No restart or configuration change needed on your end

If you set up a new instance instead, use the Claim Code flow to link it to your new license.

"Custom domains are not available on your plan"

Your plan doesn't include the custom domains feature. Custom domains require a Starter plan or higher. Upgrade at kuploy.app/billing.

"Custom domain limit reached"

You've used all custom domain slots for your plan. To add more:

• Remove unused custom domains to free up slots
• Upgrade your plan for a higher limit

"Domain purchasing requires an Enterprise plan"

The domain purchase feature is only available on the Enterprise plan. If you need to buy and manage domains directly through your platform, upgrade at kuploy.app/billing.

"Domain purchase limit reached"

You've used all purchasable domain slots for your plan. To add more:

• Remove unused purchased domains to free up slots
• Contact support for a custom limit increase

"License is suspended"

Your license has been suspended. Contact support or check your billing status at kuploy.app. While suspended, new custom domains and resource creation are blocked.

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)

tip

These environment variables serve as the bootstrap/default configuration. If you save a license hub configuration via the admin UI (Admin → Domains), the UI values take precedence over environment variables for LICENSE_KEY and LICENSE_HUB_URL. No restart is needed after changing the config in the admin UI.