> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Multi-Tenancy on the Control Plane

> Enable multi-tenant mode on a self-hosted TrueFoundry control plane and manage tenants from the admin dashboard.

<Note>
  **This guide is applicable only if you are self-hosting the control plane.** On the TrueFoundry-hosted control plane, multi-tenancy is already enabled and managed by TrueFoundry — you can [create additional tenants](https://app.truefoundry.com) directly from the UI without any infrastructure changes.
</Note>

A single TrueFoundry control plane can host multiple isolated **tenants**. Each tenant has its own users, teams, virtual accounts, SSO configuration, identity providers, and resources — see [Identity and Access Management Overview](/docs/platform/user-team-account-management) for the full mental model.

By default, a self-hosted control plane runs in **single-tenant** mode. This guide explains how to switch it to **multi-tenant** mode and then create and manage tenants from the admin dashboard.

<Warning>
  Multi-tenancy on a self-hosted control plane is part of TrueFoundry's higher-tier enterprise plan. Reach out to the TrueFoundry team before enabling it on your deployment.
</Warning>

## Architecture

In multi-tenant mode, the control plane serves each tenant on its own subdomain under a shared `base_domain`:

| Domain                   | Purpose                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `<base_domain>`          | Reserved for the control plane host. The admin dashboard at `<base_domain>/admin/` is used to create and manage tenants. |
| `<tenant>.<base_domain>` | Tenant-specific URL where users of that tenant log in and operate. Each tenant gets its own subdomain.                   |

Every other component of the control plane — `servicefoundryServer`, `tfy-llm-gateway`, `tfyK8sController`, and `mlfoundryServer` — must be told that it is running in multi-tenant mode through the `MULTITENANT` flag.

## Enable multi-tenant mode

Multi-tenancy is enabled by updating your `truefoundry-values.yaml` (the values file passed to the `truefoundry` Helm chart) and upgrading the release.

<Steps>
  <Step title="Pick a base domain">
    Choose a base domain that is dedicated to your control plane, for example `app.example.com`. Every tenant will be hosted on a subdomain of this domain (for example `team-a.app.example.com`, `team-b.app.example.com`).

    You must own this domain and be able to create a wildcard DNS record (`*.<base_domain>`) pointing to the control plane's load balancer or ingress, along with a wildcard TLS certificate that covers `*.<base_domain>`.
  </Step>

  <Step title="Update truefoundry-values.yaml">
    Add the multi-tenant flags to each microservice and configure the virtual service to accept the wildcard host:

    ```yaml truefoundry-values.yaml theme={"dark"}
    base_domain: app.example.com

    global:
      virtualservice:
        hosts:
          - "*.<base_domain>"

    servicefoundryServer:
      env:
        MULTITENANT: true
        FE_MULTITENANT_ENABLED: true
        TENANT_HOST_CONTROL_PLANE_BASE_DOMAIN: <base_domain>
        FE_TENANT_BASE_DOMAIN: <base_domain>

    tfy-llm-gateway:
      env:
        MULTITENANT: true

    tfyK8sController:
      env:
        MULTITENANT: true

    mlfoundryServer:
      env:
        MULTITENANT: true
    ```

    | Variable                                | Component                  | Purpose                                                                                    |
    | --------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------ |
    | `base_domain`                           | Helm values                | Base domain used to derive per-tenant subdomains.                                          |
    | `global.virtualservice.hosts`           | Istio virtual service      | Routes all traffic for `*.<base_domain>` to the control plane.                             |
    | `MULTITENANT`                           | All control plane services | Switches each backend service into multi-tenant mode so it scopes data and APIs by tenant. |
    | `FE_MULTITENANT_ENABLED`                | `servicefoundryServer`     | Enables multi-tenant UI flows, including the admin dashboard at `/admin/`.                 |
    | `TENANT_HOST_CONTROL_PLANE_BASE_DOMAIN` | `servicefoundryServer`     | Base domain used by the backend to construct tenant URLs.                                  |
    | `FE_TENANT_BASE_DOMAIN`                 | `servicefoundryServer`     | Base domain used by the frontend when redirecting users to their tenant.                   |
  </Step>

  <Step title="Upgrade the Helm release">
    Apply the updated values:

    ```bash theme={"dark"}
    helm upgrade --install truefoundry oci://tfy.jfrog.io/tfy-helm/truefoundry \
      -n truefoundry --create-namespace \
      -f truefoundry-values.yaml
    ```

    Once the rollout completes, the control plane is running in multi-tenant mode and the admin dashboard becomes available.
  </Step>
</Steps>

<Warning>
  Once a control plane is switched to multi-tenant mode, it cannot be reverted to single-tenant mode. Make sure you intend to run multiple tenants on this control plane before enabling it.
</Warning>

## Manage tenants from the admin dashboard

Once multi-tenancy is enabled, the parent admin can create and manage tenants from the **Tenants Dashboard** at `<control-plane-url>/admin/`.

<Info>
  The **parent (admin) tenant** is the tenant defined by `global.tenantName` in your `truefoundry-values.yaml` when the control plane was first installed (see [Deploy Control Plane and Gateway Plane](/docs/platform/deploy-control-plane-and-gateway-plane)). Only admins of this tenant can access `<control-plane-url>/admin/` and create or manage other tenants. Admins of any other tenant only have admin rights inside their own tenant.
</Info>

### Create a new tenant

<Steps>
  <Step title="Open the Tenants Dashboard">
    Log in to the **parent (admin) tenant** and navigate to:

    ```
    https://<your-control-plane-url>/admin/
    ```

    The **Tenants Dashboard** lists every tenant on the control plane along with its endpoint, tenant admins, user count, virtual accounts, teams, and creation date.

    <Frame caption="Tenants Dashboard listing every tenant on the control plane">
      <img src="https://mintcdn.com/truefoundry/xnxwG9wbAPzCd_DD/images/docs/platform/controlplane-multitenant-tenants-dashboard.png?fit=max&auto=format&n=xnxwG9wbAPzCd_DD&q=85&s=78aa6d67988d8814fe8a3f953bb25e81" alt="Tenants Dashboard showing list of tenants with name, endpoint, admins, users, virtual accounts, teams, and creation date" width="1024" height="441" data-path="images/docs/platform/controlplane-multitenant-tenants-dashboard.png" />
    </Frame>
  </Step>

  <Step title="Open the Create Tenant drawer">
    Click **Create Tenant** in the top-right corner of the Tenants Dashboard.

    <Frame caption="Create Tenant drawer with tenant name and tenant admin email fields">
      <img src="https://mintcdn.com/truefoundry/xnxwG9wbAPzCd_DD/images/docs/platform/controlplane-multitenant-create-tenant.png?fit=max&auto=format&n=xnxwG9wbAPzCd_DD&q=85&s=477011c12fdb8c51870301acc7df919b" alt="Create Tenant side drawer showing Tenant Name and Tenant Admin Email input fields" width="1024" height="495" data-path="images/docs/platform/controlplane-multitenant-create-tenant.png" />
    </Frame>
  </Step>

  <Step title="Provide tenant details">
    Fill in:

    * **Tenant Name** — used to construct the tenant URL as `<tenant-name>.<base_domain>`. Use lowercase letters, numbers, and hyphens only.
    * **Tenant Admin Email** — the email address of the first user who will administer this tenant. They will receive the invite email and become the tenant's first admin.

    Click **Create Tenant** to provision the tenant. The new tenant immediately appears on the Tenants Dashboard.
  </Step>

  <Step title="Tenant admin receives an invite email">
    The tenant admin receives a `Welcome to TrueFoundry` email with a **Setup Your Account** button.

    <Frame caption="Invite email sent to the tenant admin after a tenant is created">
      <img src="https://mintcdn.com/truefoundry/xnxwG9wbAPzCd_DD/images/docs/platform/controlplane-multitenant-invite-email.png?fit=max&auto=format&n=xnxwG9wbAPzCd_DD&q=85&s=cbb17824d7659f4adc10476497498cd1" alt="Welcome to TrueFoundry email containing a Setup Your Account button and a fallback web address" width="1024" height="952" data-path="images/docs/platform/controlplane-multitenant-invite-email.png" />
    </Frame>
  </Step>

  <Step title="Tenant admin activates their account">
    Clicking **Setup Your Account** opens the activation page on the new tenant's URL. The admin sets their first name, last name, and password, then signs in to the new tenant.

    <Frame caption="Activate your account page where the tenant admin sets their initial password">
      <img src="https://mintcdn.com/truefoundry/xnxwG9wbAPzCd_DD/images/docs/platform/controlplane-multitenant-activate-account.png?fit=max&auto=format&n=xnxwG9wbAPzCd_DD&q=85&s=ddb0fd95562af8b347601ce4b939170a" alt="Activate your account form with First Name, Last Name, Password, and Verify Password fields" width="1024" height="732" data-path="images/docs/platform/controlplane-multitenant-activate-account.png" />
    </Frame>

    <Note>
      This password flow is only used for the initial tenant admin login. Once they are in, the tenant admin can set up SSO and switch the tenant to SCIM, JIT, or invite-only provisioning — see [Manage Users](/docs/platform/user-management).
    </Note>
  </Step>

  <Step title="Tenant admin configures their tenant">
    Once logged in, the tenant admin can:

    * Set up [SSO](/docs/sso) for the tenant (each tenant has its own SSO settings).
    * Choose a [user provisioning mode](/docs/platform/user-management#user-provisioning) — SCIM, JIT, or invite-only.
    * Invite additional users and create [teams](/docs/platform/team-management) and [virtual accounts](/docs/platform/virtual-account-management).
    * Connect compute planes and start deploying workloads.
  </Step>
</Steps>

### Manage existing tenants

From the **Tenants Dashboard**, platform admins can:

* **Open a tenant** by clicking its endpoint to navigate to the tenant URL.
* **Search** for a tenant by name using the search box in the top-right.
* **Inspect tenant metadata** — admins, user count, virtual accounts, teams, and creation date — directly from the table.
* **Update tenant settings** using the gear icon at the end of each row.

<Warning>
  Tenants are designed to be fully isolated. Users, teams, virtual accounts, and resources cannot be shared across tenants. If multiple groups need to share resources, they should operate inside the same tenant and use teams and roles to scope access.
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="Can I switch a multi-tenant control plane back to single-tenant mode?">
    No. Once a control plane is switched to multi-tenant mode, it cannot be reverted to single-tenant mode. Confirm that you intend to host multiple tenants before enabling multi-tenancy.
  </Accordion>

  <Accordion title="Can each tenant have its own SSO and identity providers?">
    Yes. SSO, provisioning mode, identity providers, roles, users, and teams are all scoped to the tenant. Each tenant admin configures these independently from their tenant URL.
  </Accordion>

  <Accordion title="Do tenants share clusters and compute planes?">
    Compute planes are connected per tenant. Two tenants on the same control plane do not automatically share clusters or workloads — each tenant connects its own compute planes and manages its own resources.
  </Accordion>

  <Accordion title="Who can access the /admin/ dashboard?">
    Only users who are admins on the **parent tenant** — the tenant set as `global.tenantName` in your control plane Helm values — can access `<control-plane-url>/admin/`. Admins of any other tenant only have admin rights inside their own tenant.
  </Accordion>
</AccordionGroup>