> 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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tumbler.app/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.