> For the complete documentation index, see [llms.txt](https://docs.tumbler.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tumbler.app/readme.md).

# Overview

## Who this is for

This documentation is for VPN providers and server owners who already have a subscription link or an endpoint that returns configs. Tumbler connects that subscription through the mobile app, while the backend fetches, normalizes, and delivers the configuration to the client.

## Main flow

In most cases you do not need to change your infrastructure.

1. You already have a subscription URL, for example `https://provider.example.com/sub/user-token`.
2. The URL returns configs: raw `vless://...`, a base64 subscription, JSON `links`/`nodes`, Xray JSON, or sing-box JSON.
3. You build an add link for Tumbler:

   ```
   tumbler://add?link=<url-encoded subscription URL>
   ```
4. The user opens the link or scans a QR code.
5. The app sends the original link to the backend. The backend fetches the subscription, validates the format, normalizes nodes, and returns an encrypted runtime payload to the client.

If the original subscription URL must not be exposed to the user, use `crypt3`: the provider returns an encrypted source link such as `schema://crypt3/<token>` instead of the raw HTTPS URL, wrapped in the same `tumbler://add?link=...` add link.

## Start here

* [Quick start](/getting-started/quickstart.md) - if you already have a subscription URL.
* [Add link or QR code for Tumbler](/getting-started/add-link.md) - the exact `tumbler://add?link=...` format.
* [Response formats](/subscription-contract/response-formats.md) - what your endpoint may return.
* [Subscription examples](/subscription-contract/examples.md) - minimal raw VLESS and JSON examples.

## What can be configured later

* Metadata: profile title, Support/Manage buttons, limits, mirrors, new URL, quota/expiry.
* Balancing: node order by RTT or active connections.
* URL protection: `crypt3`, short tokens, signatures, fetcher restrictions.
* **\[PAID]** Advanced Connection Control: subscription/config/group limits, soft/hard modes, and callbacks.

## Common mistakes to avoid

* Public add link for Tumbler: `tumbler://add?link=<url-encoded source>`.
* Source link inside `link`: a regular `https://...` subscription URL or `schema://crypt3/<token>`.
* `tumbler://add/<url>` as a path-style format is not the current contract. Use the `link` query parameter.
* The term is spelled `crypt3`, not `cryp3`.

## Navigation

* [SUMMARY.md](https://github.com/evasionlab/tumbler.backend/blob/main/provider-docs/en/SUMMARY.md) - English GitBook navigation.
* [glossary.md](/glossary.md) - terms.
* [changelog.md](/changelog.md) - public contract and documentation changes.

## Public contract rules

* Do not document internal tables, Redis keys, secrets, or details outside the provider contract.
* Keep all keys, HTTP headers, JSON fields, and status codes in their original form.
* Mark paid features as **\[PAID]**.
* When the public contract changes, update [changelog.md](/changelog.md).