From a8971524d6e17366e12da0af08f74c2dac672cbd Mon Sep 17 00:00:00 2001
From: eric <eric.y.corsican@gmail.com>
Date: Thu, 19 Mar 2026 07:17:33 +0800
Subject: [PATCH] Add MPTP usage

---
 README.md          |   2 +-
 docs/mptp_usage.md | 125 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+), 1 deletion(-)
 create mode 100644 docs/mptp_usage.md

diff --git a/README.md b/README.md
index 53be6a1..bd9f5da 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ A versatile and efficient proxy framework.
 | AMux | ✅ | ✅ | Leaf specific multiplexing |
 | Obfs | ❌ | ✅ | Simple obfuscation |
 | Reality | ❌ | ✅ | Xray Reality |
-| MPTP | ✅ | ✅ | Multi-path Transport Protocol (Aggregation) ([Architecture](docs/mptp_architecture.md)) |
+| MPTP | ✅ | ✅ | Multi-path Transport Protocol (Aggregation) ([Architecture](docs/mptp_architecture.md), [Usage](docs/mptp_usage.md)) |
 
 ### Traffic Control
 
diff --git a/docs/mptp_usage.md b/docs/mptp_usage.md
new file mode 100644
index 0000000..d342e5f
--- /dev/null
+++ b/docs/mptp_usage.md
@@ -0,0 +1,125 @@
+# MPTP Usage
+
+## Overview
+
+MPTP (Multipath Transport Protocol) combines multiple outbound paths into one logical transport channel.
+In Leaf, the common deployment is:
+
+- Client side: local `socks` inbound + `mptp` outbound
+- Server side: `mptp` inbound + `direct` outbound
+
+## Configuration
+
+### JSON Config
+
+Client example (`client.json`):
+
+```json
+{
+  "inbounds": [
+    {
+      "protocol": "socks",
+      "address": "127.0.0.1",
+      "port": 1086
+    }
+  ],
+  "outbounds": [
+    {
+      "protocol": "mptp",
+      "settings": {
+        "actors": [
+          "direct1",
+          "direct2"
+        ],
+        "address": "127.0.0.1",
+        "port": 3001
+      }
+    },
+    {
+      "protocol": "direct",
+      "tag": "direct1"
+    },
+    {
+      "protocol": "direct",
+      "tag": "direct2"
+    }
+  ]
+}
+```
+
+Server example (`server.json`):
+
+```json
+{
+  "inbounds": [
+    {
+      "protocol": "mptp",
+      "address": "0.0.0.0",
+      "port": 3001
+    }
+  ],
+  "outbounds": [
+    {
+      "protocol": "direct"
+    }
+  ]
+}
+```
+
+Key fields:
+
+- `outbounds[].protocol = "mptp"`: enables MPTP client outbound
+- `settings.actors`: list of outbound tags used as sub-connections
+- `settings.address`, `settings.port`: MPTP server address and port
+- `inbounds[].protocol = "mptp"`: enables MPTP server inbound listener
+
+### conf Config
+
+MPTP outbound can also be configured in `[Proxy Group]`:
+
+```conf
+[Proxy Group]
+MptpOutTag = mptp, actor1, actor2, actor3, address=1.2.3.4, port=10000
+```
+
+## Running
+
+Build:
+
+```bash
+cargo build -p leaf-cli --release
+```
+
+Run server:
+
+```bash
+./target/release/leaf -c server.json
+```
+
+Run client:
+
+```bash
+./target/release/leaf -c client.json
+```
+
+## Validation
+
+1. Configure your app to use local SOCKS5 proxy `127.0.0.1:1086`.
+2. Start with simple connectivity checks:
+
+```bash
+curl --socks5 127.0.0.1:1086 https://example.com
+```
+
+3. Verify configuration syntax before production startup:
+
+```bash
+./target/release/leaf -c client.json -T
+./target/release/leaf -c server.json -T
+```
+
+## Notes
+
+- `actors` should include at least two outbounds to achieve multipath aggregation.
+- Ensure each actor tag exists in `outbounds`.
+- Open server listening port (for example `3001`) in firewall/security group.