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 set aggregate limits and feature flags across all your instances.

Instance Plans (Tenant → Organizations)

These are the plans your customers (organizations) subscribe to within your kuploy-cloud instance. You define them — names, pricing, limits, and features — in your own instance, at /admin/plans, and they can never grant more than your platform plan allows.

Both layers, and every product's tiers, are explained once on Plans & the two layers. For your instance's catalog see Manage Your Plans.

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 and priced by the tenant at /admin/plans, which auto-provisions the Stripe Product and Price on save.

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