SagerNet / SagerNet/sing-box

[Bug]: iOS Personal Hotspot clients have no internet / network failure when sing-box TUN is running

Open
#4,551 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
38.2k
Forks
4.6k
Avg merge
19d 15h
Merged PRs (30d)
1

Description

Operating system

iOS

System version

1.14.0 / 1.14.1

Installation type

sing-box for iOS Graphical Client

If you are using a graphical client, please provide the version of the client.

No response

Version

Description
Body:
Describe the Bug

When Personal Hotspot (Tethering) is enabled on an iPhone running sing-box with TUN mode, client devices connected to the iPhone's Wi-Fi hotspot encounter network anomalies or complete loss of internet access (DNS lookup failures or TCP connection timeouts).

Once sing-box is stopped on the iPhone, the connected devices can immediately access the internet normally.

Steps to Reproduce
  1. Launch sing-box on iOS and start the service (TUN inbound mode enabled).
  2. Ensure the iPhone itself has normal internet access through proxy/direct rules.
  3. Turn on Personal Hotspot in iOS Settings (Settings -> Personal Hotspot -> Allow Others to Join).
  4. Connect a secondary device (e.g., PC, iPad, or Android phone) to the iPhone's Wi-Fi hotspot.
  5. Attempt to browse websites or ping domain names from the connected client device.
Expected Behavior

Devices connected to the iPhone's Personal Hotspot should either:

  • Have their traffic captured and routed properly through sing-box TUN according to routing rules, or
  • Bypass the TUN interface cleanly and access the internet directly via cellular data without connection hanging/timeouts.
Actual Behavior

Connected devices fail to establish internet connections:

  • DNS queries from hotspot clients either fail to resolve or time out.
  • TCP/UDP traffic from hotspot clients hangs or gets dropped.
  • The iPhone itself maintains normal internet access, but tethered clients cannot reach the network.
Environment Information
  • Client OS: iOS
  • sing-box Version: 1.14.0 / 1.14.1
  • Inbound Type: tun (auto_route: true, strict_route: true or default)
Minimal Configuration / Inbound snippet
{
  "inbounds": [
    {
      "type": "tun",
      "tag": "tun-in",
      "address": [
        "172.19.0.1/30",
        "fdfe:dcba:9876::1/126"
      ],
      "auto_route": true,
      "strict_route": true,
      "stack": "mixed",
      "dns_mode": "hijack"
    }
  ]
}

Additional Context
  • This issue occurs consistently regardless of whether the cellular carrier allows tethering (carrier tethering works normally when sing-box is disconnected).
  • Suspected to be related to iOS NetworkExtension routing conflicts between the bridge100 interface (hotspot virtual interface) and the NEPacketTunnel interface, or strict_route preventing tethered subnet forwarding.
Reproduction
### Minimal Configuration (config.json)

```json
{
  "log": {
    "level": "debug"
  },
  "dns": {
    "servers": [
      {
        "tag": "dns-remote",
        "address": "[https://1.1.1.1/dns-query](https://1.1.1.1/dns-query)",
        "detour": "direct"
      }
    ]
  },
  "inbounds": [
    {
      "type": "tun",
      "tag": "tun-in",
      "address": [
        "172.19.0.1/30",
        "fdfe:dcba:9876::1/126"
      ],
      "auto_route": true,
      "strict_route": true,
      "stack": "mixed",
      "dns_mode": "hijack"
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "auto_detect_interface": true,
    "final": "direct"
  }
}

Steps to Reproduce
  1. Load the minimal config above into the iOS sing-box client and start the service (TUN mode).
  2. Verify that the iPhone itself can access the internet properly via the direct outbound.
  3. On the iPhone, go to Settings -> Personal Hotspot, and enable "Allow Others to Join".
  4. Connect a client device (e.g. PC or secondary phone) to the iPhone's Wi-Fi hotspot.
  5. On the connected client device, try to browse any website or run ping 1.1.1.1.
Observed Result

The client device connected to the Personal Hotspot experiences DNS lookup failures and TCP timeout / connection hang, while the host iPhone retains normal network connectivity. Disconnecting sing-box on the iPhone immediately restores internet access for the hotspot clients.


Logs

Supporter
Integrity requirements
  • I confirm that I have read the documentation, understand the meaning of all the configuration items I wrote, and did not pile up seemingly useful options or default values.
  • I confirm that I have provided the server and client configuration files and process that can be reproduced locally, instead of a complicated client configuration file that has been stripped of sensitive data.
  • I confirm that I have provided the simplest configuration that can be used to reproduce the error I reported, instead of depending on remote servers, TUN, graphical interface clients, or other closed-source software.
  • I confirm that I have provided the complete configuration files and logs, rather than just providing parts I think are useful out of confidence in my own intelligence.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the failure with the minimal TUN configuration while comparing the iPhone's connectivity with a Personal Hotspot client. Investigate routing between the bridge100 interface and the NEPacketTunnel interface, including the effects of auto_route and strict_route. Done means hotspot clients retain DNS and TCP/UDP connectivity while TUN remains enabled.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, ios
Domain
mobile-dev, networking
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.