# Config Setup ## 1. Overview We use **YAML** format for configuration files. With the config, you can: * Define all settings used for connecting to the VPN. * Set tunneling rules, if needed. * Update settings to apply new connection rules. * Monitor server health to ensure reliable VPN connections. You can also include headers along with the configuration in the server response. [#id-4.-headers-usage](#id-4.-headers-usage "mention") Xray configs can also be processed, but we recommend using YAML for simplicity and full compatibility. ## 2. Standart Configs Example Below is a typical configuration file in YAML format that the app expects. Some field is explained for clarity. {% embed url="" %} ```yaml # Fill in your subscription URL. Names must not be duplicated. proxy-providers: provider1: url: "" type: http interval: 86400 health-check: {enable: true,url: "https://www.gstatic.com/generate_204", interval: 300} override: additional-prefix: "[provider1]" provider2: url: "" type: http interval: 86400 health-check: {enable: true,url: "https://www.gstatic.com/generate_204",interval: 300} override: additional-prefix: "[provider2]" proxies: - name: "Direct" type: direct udp: true mixed-port: 7890 ipv6: true allow-lan: true unified-delay: false #We recommend setting this to true. In Rabbit Hole, true is applied by default if the field is left empty. tcp-concurrent: true external-controller: 127.0.0.1:9090 external-ui: ui external-ui-url: "https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip" geodata-mode: true geox-url: geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip-lite.dat" geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat" mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country-lite.mmdb" asn: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/GeoLite2-ASN.mmdb" find-process-mode: strict global-client-fingerprint: chrome profile: store-selected: true store-fake-ip: true sniffer: enable: true sniff: HTTP: ports: [80, 8080-8880] override-destination: true TLS: ports: [443, 8443] QUIC: ports: [443, 8443] skip-domain: - "Mijia Cloud" - "+.push.apple.com" tun: enable: true stack: mixed dns-hijack: - "any:53" - "tcp://any:53" auto-route: true auto-redirect: true auto-detect-interface: true dns: enable: true ipv6: true enhanced-mode: fake-ip fake-ip-filter: - "*" - "+.lan" - "+.local" - "+.market.xiaomi.com" default-nameserver: - tls://223.5.5.5 - tls://223.6.6.6 nameserver: - https://doh.pub/dns-query - https://dns.alidns.com/dns-query proxy-groups: - name: Default type: select proxies: [Auto Select,Direct,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes] - name: Google type: select proxies: [Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select,Direct] - name: Telegram type: select proxies: [Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select,Direct] - name: Twitter type: select proxies: [Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select,Direct] - name: YouTube type: select proxies: [Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select,Direct] - name: NETFLIX type: select proxies: [Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select,Direct] - name: Spotify type: select proxies: [Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select,Direct] - name: Github type: select proxies: [Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select,Direct] - name: China type: select proxies: [Direct,Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select] - name: Others type: select proxies: [Default,Hong Kong,Taiwan,Japan,Singapore,United States,Other Regions,All Nodes,Auto Select,Direct] # Separator, region groups below - name: Hong Kong type: select include-all: true exclude-type: direct filter: "(?i)港|hk|hongkong|hong kong" - name: Taiwan type: select include-all: true exclude-type: direct filter: "(?i)台|tw|taiwan" - name: Japan type: select include-all: true exclude-type: direct filter: "(?i)日|jp|japan" - name: United States type: select include-all: true exclude-type: direct filter: "(?i)美|us|unitedstates|united states" - name: Singapore type: select include-all: true exclude-type: direct filter: "(?i)(新|sg|singapore)" - name: Other Regions type: select include-all: true exclude-type: direct filter: "(?i)^(?!.*(?:🇭🇰|🇯🇵|🇺🇸|🇸🇬|🇨🇳|港|hk|hongkong|台|tw|taiwan|日|jp|japan|新|sg|singapore|美|us|unitedstates)).*" - name: All Nodes type: select include-all: true exclude-type: direct - name: Auto Select type: url-test include-all: true exclude-type: direct tolerance: 10 rules: - GEOIP,lan,Direct,no-resolve - GEOSITE,github,Github - GEOSITE,twitter,Twitter - GEOSITE,youtube,YouTube - GEOSITE,google,Google - GEOSITE,telegram,Telegram - GEOSITE,netflix,NETFLIX - GEOSITE,spotify,Spotify - GEOSITE,CN,China - GEOSITE,geolocation-!cn,Others - GEOIP,google,Google - GEOIP,netflix,NETFLIX - GEOIP,telegram,Telegram - GEOIP,twitter,Twitter - GEOIP,CN,China - MATCH,Others ``` ## 3. Processing Logic **1. UDP for VLESS** For VLESS connections, UDP is automatically enabled to ensure proper functionality of services such as VoIP. *** **2. Unified Delay** Unified-delay is enabled by default to provide consistent latency measurements across all proxies. *** **3. Basic Mode (GUI behavior)** In Basic mode, the GUI automatically selects available outbounds. All proxies defined in proxies and inline proxy-providers are collected. * When the user selects an outbound in Basic mode, it is applied to all selectors in the config where that outbound exists. * If a selector does not contain the chosen outbound, the provider’s default rules remain unchanged. This allows simplified proxy switching for non-advanced users. *** **4. Dynamic Switch** A dynamic switching group is automatically added to the config: * A new URLTEST group named urltestrabbithole is created. * All proxies from proxies are included in this group. * Proxies marked as hidden or filtered by the user are excluded. This group is used for automatic proxy testing and selection. Dynamic Switch is only available in Basic mode and is disabled in Pro mode. *** **5. iOS-specific Processing** When running on iOS, several parameters are adjusted: * disableKeepAlive = true * findProcessMode = off * profile = null Additionally, ruleProviders\[].sizeLimit is set dynamically: * Minimum: 2 MB * Recommended maximum: 25–30 MB *** **6. Tunneling / Routing** Routing behavior depends on the tunneling mode selected in the app. * Tunneling OFF → GLOBAL mode is applied. * Excluded / Included mode → RULE mode is applied. When rule-based routing is enabled: * The sniffer is activated with predefined settings. * All routing rules defined in the provider config are removed. * The app applies user-defined routing rules configured inside the application. *** **7. Config Format Conversion** Configs provided in V2Ray or Outline formats are automatically processed and converted into the Mihomo-compatible format before being used by the app. ## 4. Headers Usage You can use custom **headers** to flexibly configure the app. ```yaml rabbit hole headers: use-progress-bar: 1 / 0 # health (0) by default pro-mode: off / on # off by default protocols-hidden: 1 / 0 # 0 by default default headers: profile-title: VlBOIG5hbWU= # base64 subscription-userinfo: upload=0; download=17084549; total=1073741824000; expire=1774990740 # traffic in bytes, expire unix time subscription-refill-date: 1775002200 # unix time support-url: https://example.com ``` We send headers every time we request the configuration from the provider’s server. This usually happens when adding or updating a subscription. ```yaml headers: x-hwid: 03A813E5-83AD-4CF5-892C-C511762E25CC x-device-model: iPhone14,1 x-device-os: iOS x-ver-os: 26.1 User-Agent: Clash-Meta/RabbitHole (Build #versionNumber; language #lang) ``` ## 5. Tips Follow these recommendations to ensure stable behavior and better compatibility with the app. #### Place the main selector first The main selector should be placed first in the config so it appears correctly in Basic mode. By *main selector*, we mean the selector that is intended to handle all services and general traffic. *** #### Be mindful of iOS memory limits iOS has a 50 MB limit for VPN extension. Avoid adding excessively large rule providers to the config. *** #### Recommended ruleProviders size We do not recommend exceeding 25–30 MB for the total size of ruleProviders, as larger rule sets may affect performance and stability. *** #### Avoid placing Hysteria first in fallback groups Do not place Hysteria proxies as the first proxy in a fallback group, as this may lead to unstable behavior when the client switches between proxies. --- # Agent Instructions: 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: ``` GET https://rabbit-hole-1.gitbook.io/rabbit-hole-docs/for-devs/config-setup.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.