DeckBridge

DeckBridge is a self-contained Decky Loader plugin that gives Linux handhelds transparent TCP internet access through supported phone-sharing apps. Users connect the device to the phone's Wi-Fi network, select the matching provider, and press the connection card. No Steam or system proxy profile is required.

Providers

Provider	Phone platform	Endpoint	Status
PdaNet+ Wi-Fi Direct	Android	192.168.49.1:8000 HTTP CONNECT	Validated on Steam Deck
NetShare Wi-Fi Direct	Android	192.168.49.1:8282 HTTP CONNECT	Validated on Steam Deck
Egern Personal Hotspot	iOS	Hotspot gateway port 3080	Validated on Legion Go with SteamOS

Egern must enable its HTTP proxy and external connections. Its documented defaults are http_port: 3080 and allow_external_connections: true.

Features

• One toggle card for Connect and Disconnect, with emergency Restore in Settings.
• Automatic nftables or userspace-TUN routing with one HTTP CONNECT engine.
• Bundled x86_64 and ARM64 TUN executables; no runtime downloads are required.
• Per-link DNS-over-HTTPS forwarding through the selected phone proxy.
• Isolated inet deckbridge nftables table on supported kernels; otherwise two temporary /1 routes target a DeckBridge-owned TUN interface.
• Wi-Fi, routes, DNS, and NetworkManager connectivity state are preserved and restored.
• Worker recovery across temporary phone disconnects and suspend/resume.
• Automatic sanitized error report at ~/Desktop/DeckBridge-error-report.txt.
• On-demand sanitized debug bundle at ~/Desktop/DeckBridge-debug-bundle.txt.
• No downloads, compilation, or user-installed runtime dependencies.

Limitations

DeckBridge currently routes IPv4 TCP. PdaNet and NetShare do not expose a general UDP tunnel. Egern provides SOCKS5 UDP capabilities, but DeckBridge does not integrate that path yet. Games that require UDP-only networking, voice chat, or low-latency streaming may not work.

Installation

Download the release ZIP without extracting it. In Decky Loader, enable Developer Mode, open the Developer section, choose Install Plugin from ZIP, and select the DeckBridge archive. Leave SteamOS network proxy settings off.

The release archive has the required Decky layout:

DeckBridge/
  plugin.json
  package.json
  main.py
  LICENSE
  THIRD_PARTY_NOTICES.md
  bin/
  dist/index.js
  deckbridge/

How it works

DeckBridge records the active Wi-Fi interface, gateway, routes, DNS servers, and NetworkManager connectivity setting under /run/deckbridge/. It launches only the transient services required by the selected routing backend:

• deckbridge-proxy.service
• deckbridge-doh.service
• deckbridge-tun.service
• deckbridge-watchdog.service

Only TCP traffic leaving the active Wi-Fi interface is redirected. Loopback, link-local, multicast, broadcast, the local subnet, gateway, DNS servers, and the selected upstream proxy are excluded to prevent loops and preserve local services. Disconnect and Restore stop only DeckBridge-owned services and remove only table inet deckbridge or the DeckBridge TUN and its two routes.

Development

pnpm install
pnpm run test
pnpm run build
python3 -m unittest discover -s tests -v
python3 scripts/package_release.py

The packaging script creates a Decky-compatible ZIP in releases/ with the required top-level DeckBridge/ directory.

Validation

PdaNet acceptance testing includes Steam sign-in and Store access, a complete 577 MB game download, Firefox Flatpak browsing, disconnect/reconnect recovery, suspend/resume, reboot cleanup, and restoration of owned network state. See docs/STEAMOS_TEST_RESULTS_2026-07-12.md.

The release has been validated with PdaNet+ and NetShare on Steam Deck running SteamOS, Egern on Legion Go running SteamOS, Egern on ROG Ally X running Bazzite, and the ARM64 userspace-TUN fallback on Odin 2 running Armada. See docs/RELEASE_VALIDATION_0.3.6.md and docs/ARMADA_TUN_VALIDATION_2026-07-13.md.

License

DeckBridge is MIT licensed. Its separately invoked bundled sing-box executables are GPL-3.0-or-later; see THIRD_PARTY_NOTICES.md.