Concepts & Architecture

Understand how the Kuploy ecosystem fits together and the key terms used throughout this documentation.

Ecosystem Overview

Kuploy is composed of three components that work together:

┌─────────────────────────────────────────────────────────────────┐
│                        kuploy.app                               │
│                  (Licensing & Billing Hub)                       │
│                                                                 │
│  Manages: tenant accounts, platform plans, license keys,        │
│           aggregate quotas, claim codes, Stripe subscriptions    │
└────────────┬────────────────────────────┬───────────────────────┘
             │ license sync               │ license sync
             ▼                            ▼
┌────────────────────────┐  ┌────────────────────────┐
│   kuploy-cloud         │  │   kuploy-cloud         │
│   (Instance A)         │  │   (Instance B)         │
│                        │  │                        │
│  Tenant's deployment   │  │  Another instance      │
│  platform for their    │  │  under the same        │
│  customers (orgs)      │  │  license                │
└────────────────────────┘  └────────────────────────┘
        │                           │
        ▼                           ▼
   Orgs deploy apps            Orgs deploy apps
   (developers)                (developers)

kuploy (Open Source Core)

The foundational deployment engine. Provides:

• Git-based deployments with multiple build methods (Nixpacks, Dockerfile, Buildpacks)
• Managed databases (PostgreSQL, MySQL, MariaDB, MongoDB, Redis)
• Automatic SSL via Let's Encrypt
• Real-time monitoring and logging
• Container orchestration on Kubernetes

kuploy-cloud (Commercial Edition)

Extends the open-source core with multi-tenant features:

• Organization billing — Stripe-based subscription plans for end-user organizations
• License enforcement — Quota limits synced from kuploy.app
• Admin dashboard — Platform administration (Stripe config, SMTP, theme/branding, admin management)
• Team management — Organizations, roles, and access control
• White-label branding — Remove Kuploy branding (Enterprise plan)

kuploy.app (Licensing Hub)

The centralized licensing authority that kuploy-cloud instances connect to:

• Tenant accounts — ISPs/ITSPs sign up and manage their subscriptions
• License keys — Issued to tenants, linked to instances via claim codes or manual configuration
• Aggregate quotas — Usage tracked across all instances under a license
• Feature flags — Controls which capabilities are available per plan tier

Two Types of Plans

Kuploy has two distinct billing dimensions. Understanding the difference is essential.

Platform Plans (kuploy.app → Tenant)

These are the plans you subscribe to as a tenant at kuploy.app. They control what your kuploy-cloud instances can do.

Plan	Instances	Key Features
Hobby	1	Basic deployment, 1 project
Starter	1	Custom domains, 5 projects
Growth	1	AI assistant, multi-server, 20 projects
Business	3	Priority support, 50 projects
Enterprise	Unlimited	Custom pricing, white-label, domain purchase, unlimited

Platform plans set aggregate limits across all your instances — projects, apps, databases, domains, team members, build minutes, and storage.

For current pricing, see kuploy.app/pricing.

Instance Plans (Tenant → Organizations)

These are the plans your customers (organizations) subscribe to within your kuploy-cloud instance. You define plans — including pricing, limits, and features — in kuploy.app under Customers > Plans.

Typical setup (customizable by each tenant):

Plan	Description
Free	Trial tier for new organizations
Pro	For small teams with moderate usage
Business	For larger organizations needing more resources

Instance plans set per-organization limits within a single kuploy-cloud instance. The plan catalog (names, pricing, limits, features) is automatically synced to every kuploy-cloud instance during license sync. On sync, kuploy-cloud auto-provisions matching Stripe Products and Prices using the tenant's Stripe keys — no manual Stripe product setup required.

See the Cloud Billing Setup guide for connecting Stripe to your kuploy-cloud instance.

Key Terms

Term	Definition
Tenant	An ISP, ITSP, or hosting provider who runs a kuploy-cloud instance. Subscribes to a platform plan at kuploy.app.
Organization (Org)	A customer of the tenant. Deploys applications on the tenant's kuploy-cloud instance. Subscribes to an instance plan.
Developer	A member of an organization who deploys and manages applications.
Instance	A single kuploy-cloud deployment, linked to a license. A tenant can run multiple instances depending on their plan.
License	A key (lic_xxx) issued at kuploy.app that authorizes a kuploy-cloud instance to operate. Carries plan limits and feature flags.
Claim Code	A short-lived code (e.g., KPXY-4829, expires in 15 minutes) used to link a kuploy-cloud instance to a license without manual configuration.
Project	A logical grouping of related applications, databases, and resources within an organization.
Application (App)	A deployed service — a container running your code.
Build Minutes	Time consumed building application images from source code. Tracked per billing period.
License Sync	Periodic communication between a kuploy-cloud instance and kuploy.app to report usage and receive updated limits.
Platform Plan	Subscription at kuploy.app (Hobby/Starter/Growth/Business/Enterprise). Controls instance-level capabilities.
Instance Plan	Subscription within a kuploy-cloud instance (e.g., Free/Pro/Business). Controls per-organization limits. Defined by the tenant in kuploy.app and synced to kuploy-cloud, which auto-provisions Stripe Products/Prices.

Who Should Read What

If you are a...	Start here
Tenant admin setting up kuploy-cloud	Tenant Guide
Developer deploying applications	Developer Guide
Integrator building on the API	API Reference