> 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/advanced-connection-control.md).

# \[PAID] Advanced Connection Control

Specification of a paid feature that can be implemented 1:1. Without ACC activation, the backend behaves as in the free version (see compatibility below).

## What ACC unlocks

* `connection-limit >= 2` - without ACC the limit is forced down to `1`.
* Scope: `subscription` / `config` / `group`.
* Enforcement policies: `hard` (deny) or `soft` (allow + over-limit mark).
* Callbacks for over-limit reports - see [ACC callbacks](/features/acc-callbacks.md).
* Device priorities by `device_type` for selecting candidates in soft reports and analytics.

## Activation and capability

* Requires capability `advanced_connection_control` in `meta.capabilities`.
* ACC metadata works only when `acc-enabled: true`. If the capability is missing from `capabilities`, is not allowed by the plan (not paid), or `acc-enabled=false`, all ACC fields are ignored.
* Without ACC, any `connection-limit >= 2` is automatically clamped to `1` (basic free behavior).

## Configuration (metadata contract)

Level: subscription/node metadata. Keys are stable:

* `acc-enabled: true` - enables ACC for this subscription/config.
* `acc-connection-limit: <int>` - required connection limit in the selected scope.
* `acc-enforcement: hard|soft` - how to enforce the limit; default is `hard`.
* `acc-scope: subscription|config|group` - counter scope; default is `subscription`.
* `acc-device-priority: ios=100,ipados=90,macos=80` - optional priority string by `device_type`. Unspecified types get base priority `0`.
  * Format: `device_type=int` pairs separated by commas; spaces around pairs are allowed and trimmed.
  * Pair order does not matter; invalid or unknown `device_type` values are ignored (priority = `0`).

### Group and config identifiers

* **VLESS links:** query `group=<string>` -> `node.meta.group`; `cid=<string>` -> stable config identifier `node.meta.cid`.
* **JSON configs:** `meta: { "group": "...", "cid": "..." }`.

### Enforcement semantics

* **Hard:** when the limit is reached, a new connection attempt is denied for the selected scope (`subscription`/`config`/`group`).
* **Soft:**
  * connection is allowed, but marked as over-limit;
  * event goes to analytics/reports (callback);
  * device priorities are used to select a candidate if the report needs to indicate "who would be evicted/marked";
  * eviction logic can be extended without changing the priority format.

### Counter scopes

* `subscription` - limit for the whole subscription (default).
* `config` - separate limit for each unique `cid` (independent of group).
* `group` - separate limit for each group (`group` from meta/query).

## Configuration examples

### 1) Per-subscription, limit=3, hard

```json
{
  "meta": {
    "capabilities": ["advanced_connection_control"],
    "acc-enabled": true,
    "acc-connection-limit": 3,
    "acc-enforcement": "hard",
    "acc-scope": "subscription"
  }
}
```

### 2) Per-group, limit=2, soft; groups `eu`, `us`

```json
{
  "meta": {
    "capabilities": ["advanced_connection_control"],
    "acc-enabled": true,
    "acc-connection-limit": 2,
    "acc-enforcement": "soft",
    "acc-scope": "group"
  },
  "nodes": [
    { "link": "vless://...#EU?group=eu" },
    { "link": "vless://...#US?group=us" }
  ]
}
```

### 3) Per-config, limit=2, hard; `cid` is set

```json
{
  "meta": {
    "capabilities": ["advanced_connection_control"],
    "acc-enabled": true,
    "acc-connection-limit": 2,
    "acc-enforcement": "hard",
    "acc-scope": "config"
  },
  "nodes": [
    { "link": "vless://...#NodeA?cid=stable-config-id" }
  ]
}
```

## Backward compatibility

* If ACC is not activated for the provider (no `meta.capabilities` value `advanced_connection_control`, or `acc-enabled=false`), all `acc-*` fields are ignored; basic limits remain.
* When `connection-limit >= 2` is set without ACC entitlement, the backend forcibly reduces the value to `1` to avoid blocking access.
* Any new ACC fields must be added without changing existing keys; changes are recorded in the changelog.

## See also

* [ACC callbacks](/features/acc-callbacks.md)
* [features/overview.md](/features/overview.md)
* [features/basic-limits.md](/features/basic-limits.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/features/advanced-connection-control.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.