### Quick Start with Mihomo

Source: https://context7.com/boxproxy/box/llms.txt

A step-by-step guide to get started with Box for Root using Mihomo. This includes editing the configuration, starting the service, enabling rules, and checking status.

```bash
# 快速上手：以 Mihomo 为例
# 1. 安装模块后，编辑配置文件添加订阅链接
vi /data/adb/box/mihomo/config.yaml
# 将 proxy-providers 中的 url 替换为你的订阅链接

# 2. 启动服务并下发规则
su -c /data/adb/box/scripts/box.service start
su -c /data/adb/box/scripts/box.iptables enable

# 3. 查看运行状态
su -c /data/adb/box/scripts/box.service status

# 4. 若需切换为 sing-box 核心，修改 settings.ini 后重启
sed -i 's/bin_name=.*/bin_name="sing-box"/' /data/adb/box/settings.ini
su -c /data/adb/box/scripts/box.service restart
```

--------------------------------

### Install yq Tool

Source: https://github.com/boxproxy/box/wiki/Home

Installs or updates the `yq` command-line YAML processor. This is a utility script and requires root access.

```bash
su -c "/data/adb/box/scripts/box.tool upyq"
```

--------------------------------

### Install curl Tool

Source: https://github.com/boxproxy/box/wiki/Home

Installs or updates the `curl` utility for transferring data. This script requires root privileges.

```bash
su -c "/data/adb/box/scripts/box.tool upcurl"
```

--------------------------------

### Start and Enable Box Service

Source: https://github.com/boxproxy/box/wiki/Home

Use this command to start the Box service and enable its iptables rules. Ensure you are in a root environment.

```bash
su -c "/data/adb/box/scripts/box.service start && su -c /data/adb/box/scripts/box.iptables enable"
```

--------------------------------

### Whitelist Proxy Mode Configuration

Source: https://context7.com/boxproxy/box/llms.txt

Configuration example for whitelist proxy mode. Only specified applications will use the proxy; all others will connect directly. List package names in package.list.cfg.

```ini
# settings.ini:
# proxy_mode="whitelist"
#
# /data/adb/box/package.list.cfg:
# com.twitter.android
# com.google.android.youtube
#
# 效果: 仅以上应用走代理，其余全部直连。
```

--------------------------------

### Blacklist Proxy Mode Configuration

Source: https://context7.com/boxproxy/box/llms.txt

Configuration example for blacklist proxy mode. Specified applications will bypass the proxy, while all others will be routed through it. Requires listing package names in package.list.cfg.

```ini
# settings.ini:
# proxy_mode="blacklist"
#
# /data/adb/box/package.list.cfg:
# com.miui.player
# com.netease.cloudmusic
#
# 效果: 上述应用直连，其余应用全部走代理。
```

--------------------------------

### Global TUN Proxy Configuration

Source: https://context7.com/boxproxy/box/llms.txt

Example configuration for global TUN proxy mode using Mihomo. This is recommended for most users as it routes all traffic through the proxy core via a virtual TUN interface.

```ini
# settings.ini:
# bin_name="mihomo"
# network_mode="tun"
# proxy_mode="core"
#
# 效果: mihomo 接管全部流量，通过 TUN 虚拟网卡导流。
```

--------------------------------

### WiFi SSID Blacklist Configuration

Source: https://context7.com/boxproxy/box/llms.txt

Example for disabling the proxy service on specific WiFi networks. Configure enable_network_service_control, use_ssid_matching, use_wifi_list_mode, and wifi_ssids_list in settings.ini.

```ini
# settings.ini:
# enable_network_service_control="true"
# use_ssid_matching="true"
# use_wifi_list_mode="blacklist"
# wifi_ssids_list=("HomeWiFi" "OfficeWiFi")
#
# 效果: 连接到 HomeWiFi 或 OfficeWiFi 时自动停止代理服务。
```

--------------------------------

### Execute Box Tool Scripts

Source: https://github.com/boxproxy/box/wiki/Home

A comprehensive set of utility scripts for Box, including checks, resource management, data updates, and kernel/UI installations. All commands must be run as root.

```bash
su -c "/data/adb/box/scripts/box.tool {check|memcg|cpuset|blkio|geosub|geox|subs|upkernel [name]|upkernels [name...]|upgeox_all|upxui|upyq|upcurl|upcnip|reload|webroot|bond0|bond1|all}"
```

--------------------------------

### Manage Box Service

Source: https://github.com/boxproxy/box/wiki/Home

Control the Box service using various subcommands like start, stop, restart, status, cron, and kcron. Execute these commands as root.

```bash
su -c "/data/adb/box/scripts/box.service {start|stop|restart|status|cron|kcron}"
```

--------------------------------

### Box for Root Service Lifecycle Management: box.service

Source: https://context7.com/boxproxy/box/llms.txt

Manages the lifecycle of the proxy core process, including starting, stopping, restarting, and status checking. It also handles pre-start configuration preprocessing and cgroup resource binding.

```bash
# 启动服务（先停止残余进程，再启动核心，再刷新 WebUI）
su -c /data/adb/box/scripts/box.service start

# 停止服务
su -c /data/adb/box/scripts/box.service stop

# 重启服务（先清理 iptables 规则，再重启核心，再下发新规则）
su -c /data/adb/box/scripts/box.service restart

# 查看运行状态（显示 PID、内存、CPU、运行时间、本地 IP/DNS）
su -c /data/adb/box/scripts/box.service status
# 输出示例:
# [Info]: mihomo 服务正在运行
# [Info]: 代理模式: core + 网络模式: tun + 协议栈: mixed
# [Info]: mihomo (PID: 1234) 用户组: root:net_admin, 内存: 48 MB, 交换: 0 KB
# [Info]: mihomo CPU: 0.3%, 允许核心: 0-7
# [Info]: 电池温度: 32°C
# [Info]: mihomo 运行时间: 01:23:45
# [Info]: 本地 IP: 192.168.1.100
# [Info]: 本地 DNS: 192.168.1.1

# 启动定时任务（crond）
su -c /data/adb/box/scripts/box.service cron

# 停止定时任务
su -c /data/adb/box/scripts/box.service kcron

```

--------------------------------

### Update Specific Kernel

Source: https://github.com/boxproxy/box/wiki/Home

Installs or updates a specified kernel (e.g., sing-box). This operation requires root privileges.

```bash
su -c "/data/adb/box/scripts/box.tool upkernel sing-box"
```

--------------------------------

### CNIP Split + Forced Proxy Configuration

Source: https://context7.com/boxproxy/box/llms.txt

Example for splitting Mainland China IP addresses (direct connection) while forcing specific applications to use the proxy even for domestic IPs. Configure bypass_cn_ip and cnip_force_proxy_apps in settings.ini.

```ini
# settings.ini:
# bypass_cn_ip="true"
# bypass_cn_ip_v4="true"
# cnip_force_proxy_apps=("com.example.vpn_needed_app")
#
# 效果: 中国大陆 IP 直连绕过代理，
#       但 cnip_force_proxy_apps 中的应用访问大陆 IP 时仍走代理。
```

--------------------------------

### Apply Webroot

Source: https://context7.com/boxproxy/box/llms.txt

Synchronizes WebUI files to the module directory. Use this after updating the WebUI to ensure files are correctly placed.

```bash
su -c /data/adb/box/scripts/box.tool webroot
```

--------------------------------

### Box for Root Module Directory Structure

Source: https://context7.com/boxproxy/box/llms.txt

Illustrates the standard directory layout for the Box for Root module, showing the location of binaries, configurations, scripts, and runtime data.

```text
/data/adb/box/              # 模块工作目录
├── bin/                    # 代理核心二进制（mihomo、sing-box、xray、v2fly、hysteria、yq、curl）
├── mihomo/
│   ├── config.yaml         # Mihomo 主配置文件
│   ├── proxy_provider/     # 订阅 Proxy Provider 存放目录
│   └── dashboard/          # WebUI 目录
├── sing-box/
│   └── config.json         # sing-box 配置文件（支持 JSONC 注释）
├── xray/
│   └── config.json         # xray 配置文件
├── v2fly/
│   └── config.json         # v2fly 配置文件
├── hysteria/
│   └── config.yaml         # hysteria 配置文件
├── scripts/
│   ├── box.service         # 服务生命周期管理脚本
│   ├── box.iptables        # 透明代理规则管理脚本
│   ├── box.tool            # 更新与维护工具脚本
│   ├── box.inotify         # inotify 文件监听（配置热加载触发）
│   ├── ctr.inotify         # 网络状态监听（WiFi 切换自动启停）
│   └── net.inotify         # 网络接口状态监听
├── run/                    # 运行时目录（PID 文件、日志、状态快照）
│   ├── box.pid             # 当前核心进程 PID
│   ├── mihomo.log          # Mihomo 运行日志
│   ├── runs.log            # box.service 操作日志
│   ├── tool.log            # box.tool 操作日志
│   └── state/              # 运行时状态（UID 列表、iptables 快照等）
├── settings.ini            # 全局配置文件（核心入口，所有脚本 source）
├── package.list.cfg        # 应用黑/白名单（包名列表）
├── gid.list.cfg            # GID 黑/白名单
├── ap.list.cfg             # 热点接口允许/忽略列表
└── crontab.cfg             # 自定义定时任务
```

--------------------------------

### Set Disk I/O Weight (blkio)

Source: https://context7.com/boxproxy/box/llms.txt

Sets the disk I/O weight for running core processes. Useful for managing disk-intensive operations.

```bash
su -c /data/adb/box/scripts/box.tool blkio
```

--------------------------------

### Check Configuration Syntax

Source: https://context7.com/boxproxy/box/llms.txt

Checks the syntax of the current kernel configuration file. This is a crucial step before applying changes to prevent errors.

```bash
su -c /data/adb/box/scripts/box.tool check
```

--------------------------------

### Perform All Updates

Source: https://context7.com/boxproxy/box/llms.txt

Executes all available update commands in sequence. This is a convenient way to ensure all components are up-to-date.

```bash
su -c /data/adb/box/scripts/box.tool all
```

--------------------------------

### Box for Root Update and Maintenance Tools: box.tool

Source: https://context7.com/boxproxy/box/llms.txt

Provides a collection of maintenance operations including subscription updates, GeoX data updates, proxy core binary updates, WebUI updates, tool downloads (yq/curl), cgroup configuration, and configuration checks.

```bash
# ── 订阅管理 ──────────────────────────────────────────────
# 更新订阅并热重载（Mihomo 支持 API 热重载，无需重启）
su -c /data/adb/box/scripts/box.tool subs

# 仅更新 GeoX 数据（geoip.dat / geosite.dat / geoip.metadb 等）
su -c /data/adb/box/scripts/box.tool geox

# 同时更新订阅和 GeoX 数据
su -c /data/adb/box/scripts/box.tool geosub

# 更新 CNIP（中国大陆 IP 列表，需在 settings.ini 中启用 bypass_cn_ip）
su -c /data/adb/box/scripts/box.tool upcnip

# ── 内核更新 ──────────────────────────────────────────────

```

--------------------------------

### Bind CPU Cores (cpuset)

Source: https://context7.com/boxproxy/box/llms.txt

Binds running core processes to specific CPU cores as defined in settings.ini. This can help optimize performance and reduce context switching.

```bash
su -c /data/adb/box/scripts/box.tool cpuset
```

--------------------------------

### Update yq Tool

Source: https://context7.com/boxproxy/box/llms.txt

Updates the yq tool, which is required for automatic injection into sing-box/mihomo configurations. Run this if you encounter issues with configuration processing.

```bash
su -c /data/adb/box/scripts/box.tool upyq
```

--------------------------------

### Reload Configuration

Source: https://context7.com/boxproxy/box/llms.txt

Applies configuration changes without restarting the core service. Supports hot reloading for Mihomo and sing-box.

```bash
su -c /data/adb/box/scripts/box.tool reload
```

--------------------------------

### Manage Box Transparent Proxy Rules

Source: https://github.com/boxproxy/box/wiki/Home

Enable, disable, or renew the transparent proxy rules managed by Box. These commands require root privileges.

```bash
su -c "/data/adb/box/scripts/box.iptables {enable|disable|renew}"
```

--------------------------------

### Enhance Mode (TCP Redirect + UDP TProxy)

Source: https://context7.com/boxproxy/box/llms.txt

Configuration for Enhance mode, utilizing TCP Redirect and UDP TProxy. This is suitable for devices where the core doesn't support full TUN but does support TPROXY.

```ini
# settings.ini:
# network_mode="enhance"
# proxy_tcp="true"
# proxy_udp="true"
#
# 效果: TCP 使用 NAT Redirect，UDP 使用 TProxy，
#       适合内核不支持完整 TUN 但支持 TPROXY 的设备。
```

--------------------------------

### Update Subscriptions and Reload

Source: https://github.com/boxproxy/box/wiki/Home

This command updates the Box subscriptions and attempts to reload the service configuration. It requires root access.

```bash
su -c "/data/adb/box/scripts/box.tool subs"
```

--------------------------------

### Apply Memory Limit (memcg)

Source: https://context7.com/boxproxy/box/llms.txt

Applies memory limits to running core processes based on the value in settings.ini. Use this to manage resource consumption.

```bash
su -c /data/adb/box/scripts/box.tool memcg
```

--------------------------------

### Update WebUI

Source: https://context7.com/boxproxy/box/llms.txt

Downloads and updates the Dashboard WebUI, such as Metacubexd. Keep your WebUI current for the latest features and bug fixes.

```bash
su -c /data/adb/box/scripts/box.tool upxui
```

--------------------------------

### Box for Root Global Configuration: settings.ini

Source: https://context7.com/boxproxy/box/llms.txt

The global configuration file for Box for Root, located at /data/adb/box/settings.ini. It controls proxy core selection, network modes, ports, proxy modes, subscription URLs, CNIP bypass, and cgroup limits. Modifications require a service restart to take effect.

```ini
# ── 代理核心 ──────────────────────────────────────────────
# 可选值: mihomo | sing-box | xray | v2fly | hysteria
bin_name="mihomo"

# ── 网络模式 ──────────────────────────────────────────────
# tun       : 虚拟网卡模式（推荐，兼容性最好）
# tproxy    : 透明代理（需内核支持 TPROXY，xray/v2fly 仅支持此模式）
# redirect  : NAT 重定向（仅 TCP）
# mixed     : tun + redirect 混合
# enhance   : redirect(TCP) + tproxy(UDP) 混合
network_mode="tun"

tproxy_port="9898"   # TPROXY 监听端口
redir_port="9797"    # Redirect 监听端口
ipv6="true"          # 是否启用 IPv6 代理

# ── 代理模式 ──────────────────────────────────────────────
# core      : 全局代理（所有应用）
# blacklist : 黑名单（指定应用不代理）
# whitelist : 白名单（仅指定应用代理）
proxy_mode="core"

# ── Mihomo 订阅 ───────────────────────────────────────────
subscription_url_mihomo=("https://your-sub-url/sub1" "https://your-sub-url/sub2")
name_provide_mihomo_config=("proxy_provider1.yaml" "proxy_provider2.yaml")

# ── 大陆 IP 分流（需 ipset） ─────────────────────────────
bypass_cn_ip="false"
bypass_cn_ip_v4="false"
bypass_cn_ip_v6="false"
# 即便绕过大陆 IP，仍强制走代理的应用包名（支持多用户前缀，格式: "0:com.example.app"）
cnip_force_proxy_apps=()

# ── cgroup 资源限制 ───────────────────────────────────────
cgroup_memcg="false"
memcg_limit="100M"
cgroup_cpuset="false"
allow_cpu="0-7"
cgroup_blkio="false"

# ── GitHub 下载加速 ───────────────────────────────────────
githubtoken=""
use_ghproxy="false"
url_ghproxy="https://ghfast.top"

# ── 定时任务 ─────────────────────────────────────────────
run_crontab="false"
update_subscription="false"
update_geo="false"
interva_update="0 0,6,12,18 * * *"

```

--------------------------------

### Batch Update Multiple Kernels

Source: https://context7.com/boxproxy/box/llms.txt

Updates multiple specified kernels in a single command. This is useful for synchronizing several proxy cores at once.

```bash
su -c /data/adb/box/scripts/box.tool upkernels mihomo sing-box xray
```

--------------------------------

### Update Active Kernel (bin_name)

Source: https://context7.com/boxproxy/box/llms.txt

Updates the currently active kernel specified by bin_name. Use this command to ensure your primary proxy core is up to date.

```bash
su -c /data/adb/box/scripts/box.tool upkernel
```

--------------------------------

### Restart Box Service

Source: https://github.com/boxproxy/box/wiki/Home

Restarts the Box service, which is often necessary for configuration changes to take effect. Must be run as root.

```bash
su -c "/data/adb/box/scripts/box.service restart"
```

--------------------------------

### Box for Root Transparent Proxy Rule Management: box.iptables

Source: https://context7.com/boxproxy/box/llms.txt

Manages iptables/ip6tables rules for transparent proxying based on the network mode defined in settings.ini. It supports IPv4 and IPv6 and adapts to kernel capabilities like TPROXY, conntrack, connmark, and ipset.

```bash
# 启用透明代理规则
su -c /data/adb/box/scripts/box.iptables enable

# 禁用并清理所有透明代理规则
su -c /data/adb/box/scripts/box.iptables disable

# 重建规则（先清理旧规则，再重新下发，常用于配置变更后刷新）
su -c /data/adb/box/scripts/box.iptables renew

# ── 不同网络模式的规则行为说明 ────────────────────────────
# network_mode=tproxy   → 下发 mangle 表 TPROXY 规则 + ip rule 策略路由
# network_mode=redirect → 下发 nat 表 REDIRECT 规则
# network_mode=tun      → 下发 mangle 表标记规则 + ip rule 将流量导入 TUN 网卡
# network_mode=mixed    → tun + redirect 混合
# network_mode=enhance  → redirect(TCP) + tproxy(UDP) 混合

# ── 应用黑名单示例（配合 package.list.cfg）─────────────────
# /data/adb/box/package.list.cfg 内容（每行一个包名，支持多用户前缀）:
# com.example.exclude_app
# 10:com.example.work_profile_app  # 用户10的应用
#
# 对应 settings.ini:
# proxy_mode="blacklist"
#
# 效果: 列表中的应用不走透明代理，其余全部代理。

# ── 大陆 IP 分流示例 ──────────────────────────────────────
# settings.ini 中启用:
# bypass_cn_ip="true"
# bypass_cn_ip_v4="true"
#
# 先更新 CNIP 数据，再下发规则:
su -c /data/adb/box/scripts/box.tool upcnip
su -c /data/adb/box/scripts/box.iptables renew
# 效果: 目标为中国大陆 IP 的流量绕过代理直连。

```

--------------------------------

### Update Geo Data

Source: https://github.com/boxproxy/box/wiki/Home

Fetches and updates the GeoIP and GeoSite data used by Box for routing. Execute this command as root.

```bash
su -c "/data/adb/box/scripts/box.tool geox"
```

--------------------------------

### Reset Proxy Rules

Source: https://github.com/boxproxy/box/wiki/Home

Resets all transparent proxy rules managed by Box. This is useful for troubleshooting network connectivity issues. Requires root.

```bash
su -c "/data/adb/box/scripts/box.iptables renew"
```

--------------------------------

### Update Specific Kernel

Source: https://context7.com/boxproxy/box/llms.txt

Updates a specific kernel by its name. Use this for updating sing-box, mihomo, or xray cores.

```bash
su -c /data/adb/box/scripts/box.tool upkernel sing-box
```

```bash
su -c /data/adb/box/scripts/box.tool upkernel mihomo
```

```bash
su -c /data/adb/box/scripts/box.tool upkernel xray
```

--------------------------------

### Reset Rules and Restart Service

Source: https://github.com/boxproxy/box/wiki/Home

A troubleshooting sequence that first disables, then enables iptables rules, followed by a service restart. Use when experiencing rule anomalies or network issues. Requires root.

```bash
su -c "/data/adb/box/scripts/box.iptables disable"
su -c "/data/adb/box/scripts/box.iptables enable"
su -c "/data/adb/box/scripts/box.service restart"
```

--------------------------------

### Update curl Tool

Source: https://context7.com/boxproxy/box/llms.txt

Updates the curl utility. Ensure curl is up-to-date for reliable network operations.

```bash
su -c /data/adb/box/scripts/box.tool upcurl
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.