> 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/features/basic-limits.md).

# Basic limits

## Who this is for

Providers who want to control load and connection volume without extra paid features.

## What you can do

* Limit concurrent sessions and subscription refresh rate.
* Set TTL and caching rules.
* Tell clients about expected limits in advance.

## installation-limit (subscription)

* `installation-limit` is the active installation limit attached to the subscription.
* Slot TTL: **24 hours without activity**. Activity includes:
  * subscription `sync`;
  * connection request (`/v1/sessions/request`);
  * active session `heartbeat`.
* If an installation has no activity for 24 hours, the slot is released automatically.
* Removing the subscription from the client releases the slot immediately.
* When the limit is exceeded, issuing a new installation returns `INSTALLATION_LIMIT_EXCEEDED` (403).

## connection-limit (basic)

* Basic `connection-limit` for the free tier is binary: `0` = limit disabled, `1` = one active session allowed (values >1 are effectively treated as 1).
* "Active connection" = live VPN session (lease + heartbeat).
* When the limit is exceeded, `POST /v1/sessions/request` returns `allowed:false, reason: "CONNECTION_LIMIT_EXCEEDED"`, and the app does not connect.
* If a short lease expired after a long network loss but session metadata is still alive, the next heartbeat automatically extends the same session without re-lease.
* On heartbeat the server may still require forced disconnect: `{"ok":false,"disconnect_required":true,"disconnect_reason":"SESSION_NOT_FOUND|SUBSCRIPTION_NOT_FOUND"}`. The client must tear down the tunnel and request a new lease if needed.

## Examples

* `installation-limit: 3` - up to three active installations.
* `connection-limit: 1` - one active connection.
* `Cache-Control: public, max-age=300` - basic subscription URL caching.

## See also

* [features/overview.md](/features/overview.md)
* [operations/reliability-and-timeouts.md](/after-first-launch/reliability-and-timeouts.md)
* [subscription/metadata.md](/subscription-contract/metadata.md)

## Recommended fields

* `installation-limit` - limit for active installations.
* `connection-limit` - basic active VPN session limit.
* `subscription-userinfo` - usage, total traffic limit, and subscription expiry for the UI.
* `Cache-Control` / `ETag` - caching and predictable subscription URL updates.

## Default behavior

If limits are not set, the backend does not apply installation/connection restrictions beyond standard platform rules. Set explicit limits when they are part of your plan.

## What the user sees

* When `installation-limit` is exceeded: modal message like "Installation limit reached. Remove extra installations/devices or disconnect the subscription on an old device" (`INSTALLATION_LIMIT_EXCEEDED`).
* When `connection-limit` is exceeded: modal message "Connection limit reached. Disconnect other sessions and try again" (`CONNECTION_LIMIT_EXCEEDED`).
* Providers should add an FAQ/support instruction for freeing slots: remove extra installations/connections, wait for automatic release after 24h without activity, or delete the subscription.


---

# 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/features/basic-limits.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.