Skip to content

Composite Catalogs

Composite proxies merge categories from multiple standard proxies into one Xtream-compatible endpoint. Clients see a single login, a single playlist, and a clean curated catalog — even though the streams come from several upstreams behind the scenes.

When to reach for a composite

  • You resell access and want a single subscription that pulls the best channels from several providers.
  • You're rotating upstreams seasonally (sports packages, regional VOD) and want one stable URL for clients.
  • You want per-content-type curation: live channels from provider A, movies from provider B, series from provider C — but one client login.

How it works

flowchart LR
    classDef src   fill:#a855f7,stroke:#7e22ce,color:#fff
    classDef std   fill:#1e293b,stroke:#334155,color:#e2e8f0
    classDef comp  fill:#6366f1,stroke:#4338ca,color:#fff
    classDef user  fill:#0ea5e9,stroke:#0369a1,color:#fff

    A["Provider A<br/>upstream"]:::src
    B["Provider B<br/>upstream"]:::src
    C["Provider C<br/>upstream"]:::src

    P1["Standard proxy A"]:::std
    P2["Standard proxy B"]:::std
    P3["Standard proxy C"]:::std

    K["Composite proxy<br/>(client-facing)"]:::comp
    U["Xtream client"]:::user

    A --> P1
    B --> P2
    C --> P3

    P1 -. live .-> K
    P2 -. vod .-> K
    P3 -. series .-> K

    U --> K

Each composite category selection records id (upstream category ID) and sourceProxy (which standard proxy hosts it). tunlx routes a client's stream request back to the originating standard proxy at request time.

Build one in the dashboard

  1. Switch to Advanced mode. Composite blueprints are hidden in Simple mode.
  2. Open Add Proxy → Composite Proxy. Fill in name, thisServerHost, thisServerPort, and (recommended) publicBaseURL.
  3. Optionally set xtreamUsername and xtreamPassword so the composite has its own client credentials instead of relaying whatever each client sends.
  4. Save the composite, then open Manage Categories on it. Select the source proxy from the filter, pick categories for Live / VOD / Series, optionally set prefix or override name, and save.
  5. Open the built-in player on the composite. Confirm playback in both Proxy and Direct modes.

Select proxy blueprint

Choosing Design Composite Proxy opens the composite form. A composite has no target server of its own — it borrows categories from proxies you already have, behind one set of client credentials.

The composite proxy dialog

Pick which categories from which source proxies make up the merged catalog:

Selecting categories for a composite catalog

Configuration shape

{
  "compositeProxies": [
    {
      "name": "favorites",
      "description": "Aggregate multiple sources",
      "welcomeMessage": "Welcome to favorites",
      "thisServerHost": "0.0.0.0",
      "thisServerPort": "18000",
      "publicBaseURL": "https://favorites.example.com",
      "xtreamUsername": "combo-user",
      "xtreamPassword": "combo-pass",
      "categoryPrefix": "[Fav] ",
      "categories": {
        "live": [
          { "id": "1",  "sourceProxy": "providerA", "prefix": "[Sports] " },
          { "id": "12", "sourceProxy": "providerB" }
        ],
        "vod": [
          { "id": "44", "sourceProxy": "providerB", "name": "Movies HD" }
        ],
        "series": [
          { "id": "9",  "sourceProxy": "providerC" }
        ]
      }
    }
  ]
}

See Configuration Reference → Composite Proxies for every field and override.

Stream IDs inside a composite

Composite stream IDs are compound. They encode the source proxy and the numeric stream ID together so tunlx can route playback to the correct underlying upstream:

base64(sourceProxyName) ~ numericID

This matters when you script against composite endpoints — never strip the prefix or re-emit a naked numeric ID to a composite client. Standard proxies use plain numeric IDs as before.

Mix and match VPN routing

Composite proxies don't have their own route. They inherit egress from each source proxy individually, so you can keep a VPN-routed upstream alongside a system-routed one inside one composite without fighting the routing model.

Operations tips

  • Use a global categoryPrefix when you want a visible "brand" on every category your composite publishes (e.g. [US], [Premium]). Per-selection prefix / name overrides win when set.
  • Set publicBaseURL if any clients live outside the LAN. Playlist generation and stream redirects use it preferentially.
  • welcomeMessage appears in the Xtream message field at login — use it to label which subscription this is.