{"id":48581325,"url":"https://github.com/denmrnngp-cloud/hiddify-steam-deck","last_synced_at":"2026-04-26T15:00:51.514Z","repository":{"id":345993568,"uuid":"1188174211","full_name":"denmrnngp-cloud/hiddify-steam-deck","owner":"denmrnngp-cloud","description":"Steam Deck port of Hiddify VPN — self-extracting installer + Decky Game Mode plugin. Fork of hiddify/hiddify-app.","archived":false,"fork":false,"pushed_at":"2026-04-11T17:03:57.000Z","size":324582,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T19:27:45.355Z","etag":null,"topics":["clashmeta","decky-loader","gaming","hiddify","hysteria2","linux","proxy","reality","shadowsocks","shadowtls","sing-box","steam-deck","steamos","tuic","v2ray","vless","vmess","vpn","wireguard","xray"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denmrnngp-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T18:03:55.000Z","updated_at":"2026-04-11T17:03:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/denmrnngp-cloud/hiddify-steam-deck","commit_stats":null,"previous_names":["denmrnngp-cloud/hiddify-steam-deck"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/denmrnngp-cloud/hiddify-steam-deck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denmrnngp-cloud%2Fhiddify-steam-deck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denmrnngp-cloud%2Fhiddify-steam-deck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denmrnngp-cloud%2Fhiddify-steam-deck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denmrnngp-cloud%2Fhiddify-steam-deck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denmrnngp-cloud","download_url":"https://codeload.github.com/denmrnngp-cloud/hiddify-steam-deck/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denmrnngp-cloud%2Fhiddify-steam-deck/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32301330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clashmeta","decky-loader","gaming","hiddify","hysteria2","linux","proxy","reality","shadowsocks","shadowtls","sing-box","steam-deck","steamos","tuic","v2ray","vless","vmess","vpn","wireguard","xray"],"created_at":"2026-04-08T17:01:24.912Z","updated_at":"2026-04-26T15:00:51.496Z","avatar_url":"https://github.com/denmrnngp-cloud.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hiddify VPN — Steam Deck Port\n\n\u003cimg src=\"https://raw.githubusercontent.com/denmrnngp-cloud/hiddify-steam-deck/main/assets/cover.png\" alt=\"Hiddify VPN for Steam Deck\" width=\"100%\"/\u003e\n\n\u003e **Unofficial Steam Deck port of [hiddify/hiddify-app](https://github.com/hiddify/hiddify-app)**\n\u003e Powered by [sing-box](https://github.com/SagerNet/sing-box) · Supports VLESS/Reality, VMess, Trojan, Hysteria 2, TUIC, Shadowsocks\n\n[![Based on](https://img.shields.io/badge/based%20on-hiddify%2Fhiddify--app-blue?logo=github)](https://github.com/hiddify/hiddify-app)\n[![Platform](https://img.shields.io/badge/platform-Steam%20Deck%20%2F%20SteamOS-informational?logo=steam)](https://store.steampowered.com/steamdeck)\n[![Decky Plugin](https://img.shields.io/badge/Decky-plugin-green?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyTDQgNXY2YzAgNS4yNSAzLjQgMTAuMTUgOCAxMS4zOEM' )](https://decky.xyz)\n\nFull port of [Hiddify](https://github.com/hiddify/hiddify-app) for Steam Deck / SteamOS.\nWorks in Desktop Mode and Game Mode (via Decky plugin).\n\n## Demo\n\n\u003ca href=\"https://github.com/denmrnngp-cloud/hiddify-steam-deck/releases/download/v1.2.0/demo.mp4\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/denmrnngp-cloud/hiddify-steam-deck/main/assets/demo.gif\" alt=\"Demo — Hiddify VPN installer and VPN toggle in Desktop and Game Mode\" width=\"100%\"/\u003e\n\u003c/a\u003e\n\n▶ [Download / watch full demo (mp4)](https://github.com/denmrnngp-cloud/hiddify-steam-deck/releases/download/v1.2.0/demo.mp4)\n\n---\n\n## Release Contents\n\n| File | Description |\n|------|-------------|\n| `Hiddify-linux-x64.bin` | Self-extracting installer (~51 MB) |\n| `decky-hiddify-v1.2.0.zip` | Decky plugin for Game Mode VPN control |\n| `installer-src/` | Installer source (install.sh + all bundled files) |\n\n---\n\n## Requirements\n\n- Steam Deck (SteamOS) or Ubuntu 22.04+ / Debian 12+\n- Architecture: x86-64 (amd64)\n- For Game Mode: [Decky Loader](https://decky.xyz/) installed\n\n---\n\n## Installation\n\n### 1. Download the installer\n\nCopy `Hiddify-linux-x64.bin` to your Steam Deck (e.g. `~/Downloads/`).\n\n### 2. Run in Desktop Mode\n\nOpen **Konsole** and run:\n\n```bash\nbash ~/Downloads/Hiddify-linux-x64.bin\n```\n\nThe installer automatically:\n- Detects Steam Deck and applies the correct mode\n- Installs all files to `/opt/hiddify/`\n- Applies `patchelf` (absolute RPATH — works from any directory)\n- Applies `setcap cap_net_admin` (TUN creation without root at runtime)\n- Configures passwordless sudo for HiddifyCli\n- Configures polkit rules (no password prompts for DNS/route changes)\n- Creates a systemd user service\n- Adds a desktop shortcut (Internet category)\n- Sets the application icon\n\n### 3. Configure a VPN profile\n\nLaunch the GUI from the menu or directly:\n\n```bash\n/opt/hiddify/hiddify-gui\n```\n\nAdd a VPN configuration (subscription link or manual).\nConfig is saved to:\n```\n~/.local/share/app.hiddify.com/data/current-config.json\n```\n\n### 4. Install the Decky plugin (optional)\n\nFor VPN control from Game Mode (the `···` button):\n\n```bash\n# Copy decky-hiddify-v1.2.0.zip to Steam Deck, then:\nsudo unzip -o decky-hiddify-v1.2.0.zip -d /home/deck/homebrew/plugins/\nsudo systemctl restart plugin_loader\n```\n\n---\n\n## Uninstall\n\nRun the installer again — a menu will appear:\n\n```\nHiddify is already installed in /opt/hiddify\n\n  [1] Reinstall (update)\n  [2] Uninstall completely\n  [3] Cancel\n```\n\nSelect `2` to uninstall. Removes:\n- `/opt/hiddify/`\n- systemd user service\n- desktop shortcut and icon from `~/.local/share/`\n\n---\n\n## VPN Control from Terminal\n\n```bash\n# Start VPN\nsystemctl --user start hiddify\n\n# Stop VPN\nsystemctl --user stop hiddify\n\n# Status\nsystemctl --user status hiddify\n\n# Live logs\njournalctl --user -u hiddify -f\n```\n\n---\n\n## Technical Details\n\n### `/opt/hiddify/` Structure\n\n```\n/opt/hiddify/\n├── hiddify              # Flutter GUI (setcap + absolute RUNPATH)\n├── HiddifyCli           # VPN core (setcap + absolute RUNPATH)\n├── hiddify-gui          # Wrapper script for desktop shortcut\n├── hiddify.png          # Application icon\n├── _tools/\n│   └── patchelf         # Static patchelf (bundled)\n├── lib/\n│   ├── hiddify-core.so          # sing-box core\n│   ├── libflutter_linux_gtk.so  # Flutter runtime\n│   ├── libayatana-appindicator3.so.1  # System tray (bundled)\n│   ├── libayatana-ido3-0.4.so.0       # System tray dep (bundled)\n│   ├── libayatana-indicator3.so.7     # System tray dep (bundled)\n│   └── ... (other Flutter plugin .so files)\n└── data/\n    └── flutter_assets/   # Flutter assets, flag icons, fonts\n```\n\n### Key Port Fixes\n\n| Problem | Solution |\n|---------|----------|\n| `./lib/hiddify-core.so not found` from foreign CWD | `patchelf --replace-needed` + `--set-rpath /opt/hiddify/lib` |\n| `libayatana-appindicator3.so.1 not found` on SteamOS | Bundled from Ubuntu 22.04, patchelf on `libtray_manager_plugin.so` |\n| `operation not permitted` creating TUN | `setcap cap_net_admin,cap_net_bind_service,cap_net_raw=+eip` on both binaries |\n| `cache.db: permission denied` | CWD = `~/.local/share/app.hiddify.com` (user-writable) |\n| Caps reset after patchelf | setcap applied strictly **after** patchelf |\n| systemd user service on SteamOS | User service in `~/.config/systemd/user/` (survives OS updates) |\n| `LD_LIBRARY_PATH` ignored with setcap | Absolute RUNPATH via patchelf instead of `LD_LIBRARY_PATH` |\n| Sudo password prompt on every VPN toggle | `/etc/sudoers.d/zz-deck-nopasswd` with `NOPASSWD: ALL` (named `zz-*` to override `wheel` file alphabetically) |\n| SteamOS A/B update resets `/etc/` and `/usr/` | Plugin tries to re-apply on load; installer handles it during reinstall |\n| `pkill` killing plugin itself | Bracket trick: `pkill -f '/opt/hiddify/hiddif[y]'` — won't match plugin path |\n| `systemctl --user` failing in plugin subprocess | Set `DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus` + `XDG_RUNTIME_DIR=/run/user/1000` |\n| Hiddify GUI VPN not stopped by plugin | Stop `app-hiddify@\u003cuuid\u003e.service` by querying `systemctl list-units` for exact unit name |\n\n### Why Installation Survives SteamOS Updates\n\nSteamOS updates via A/B partition swap — only the read-only partition (`/usr`, `/etc`) changes.\nThe installer writes exclusively to:\n- `/opt/hiddify/` — mounted from the `/home` partition (persistent)\n- `~/.config/systemd/user/` — home directory (persistent)\n- `~/.local/share/` — home directory (persistent)\n\n`setcap` is stored as an xattr on the file in `/opt/hiddify/` — also persistent.\n\n### Manual VPN Start\n\n```bash\ncd ~/.local/share/app.hiddify.com\n/opt/hiddify/HiddifyCli run \\\n  -c ~/.local/share/app.hiddify.com/data/current-config.json \\\n  --tun\n```\n\n---\n\n## Decky Plugin (v1.2.0)\n\nThe `decky-hiddify` plugin adds VPN control to Quick Access Menu (the `···` button).\n\n### Features\n\n- **VPN ON / OFF toggle** — button with colored status dot (green = connected, yellow = connecting, red = off)\n- **Profile selector** — switch between VPN profiles without leaving Game Mode (VPN must be stopped first)\n- Connection status with TUN IP address display\n- Syncs with Hiddify GUI (stopping VPN from plugin also stops GUI-managed VPN via systemd unit)\n- Background monitor with push events on VPN state changes (polls every 5 s)\n- Log viewer (last 40 lines)\n- Error boundary — render errors shown in UI instead of crashing the plugin\n\n### Plugin Architecture\n\n```\ndecky-hiddify/\n├── main.py        # Backend (Python): HiddifyCli subprocess + profile management\n└── src/\n    └── index.tsx  # Frontend (React/TSX): panel UI\n```\n\n**Profile switching** reads profiles from `~/.local/share/app.hiddify.com/db.sqlite`\nand regenerates `current-config.json` via `HiddifyCli build` from the selected\nprofile config. This keeps balancer/selector/endpoints handling aligned with the\ndesktop client. VPN must be stopped before switching.\n\n**GUI sync**: when stopping VPN from the plugin, it queries `systemctl --user list-units 'app-hiddify@*.service'`\nto get the exact transient unit name, then stops it. Also sends `SIGTERM` to the `hiddify` GUI process directly.\n\n---\n\n## Build from Source\n\n### Installer\n\nThree large upstream binaries are **not** included in this repo. Download them from the\n[Hiddify release](https://github.com/hiddify/hiddify-app/releases) and place into `release/installer-src/lib/`:\n\n| File | Size | Source |\n|------|------|--------|\n| `lib/hiddify-core.so` | ~70 MB | Hiddify release (sing-box core) |\n| `lib/libflutter_linux_gtk.so` | ~32 MB | Hiddify release (Flutter runtime) |\n| `lib/libapp.so` | ~15 MB | Hiddify release (Flutter app) |\n\nThen rebuild the self-extracting installer:\n\n```bash\nmakeself --nox11 release/installer-src/ Hiddify-linux-x64.bin \"Hiddify VPN\" bash setup.sh\n```\n\n### Decky Plugin\n\n```bash\ncd decky-hiddify/\nnpm install\nnpm run build\n# Output: dist/ — copy to Steam Deck at ~/homebrew/plugins/decky-hiddify/\n```\n\n---\n\n---\n\n## Home Assistant Add-on\n\nThis repo also contains a **Home Assistant add-on** that runs Hiddify VPN (sing-box) on your HA host — routing all HA traffic through VPN.\n\nSource: [`ha-addon/`](ha-addon/)\n\n### Features\n\n- Routes **all** public traffic through VPN (TUN mode with sing-box 1.13)\n- Local LAN / HomeKit / Tuya / mDNS bypass TUN automatically (`route_exclude_address`)\n- Supports VLESS · VLESS+Reality · VMess · Trojan · Shadowsocks · Hysteria2 · TUIC\n- HA sensors: `sensor.hiddify_status`, `sensor.hiddify_ip`, `sensor.hiddify_profile`\n- Subscription URL or direct proxy URL\n\n### Install in Home Assistant\n\n1. **Settings → Add-ons → Add-on Store → ⋮ → Repositories**\n2. Add: `https://github.com/denmrnngp-cloud/hiddify-steam-deck`\n3. Install **Hiddify VPN**, set `subscription_url` in Configuration, start\n\n### Add-on Structure\n\n```\nha-addon/\n├── repository.yaml          # HA addon repository manifest\n└── hiddify/\n    ├── config.yaml          # Add-on manifest (options, ports, capabilities)\n    ├── Dockerfile           # sing-box 1.13.3 on Alpine\n    ├── run.sh               # Entrypoint: parse sub → start sing-box → monitor\n    ├── parse_sub.py         # Subscription parser → sing-box JSON config\n    ├── grpc_ctl.py          # gRPC helper (hiddify-core control)\n    └── DOCS.md              # User-facing documentation\n```\n\n### Routing Architecture\n\n```\nPublic internet traffic\n  └── TUN (tun0)  →  sing-box proxy  →  VPN server  →  internet\n\nPrivate / multicast  (route_exclude_address)\n  └── bypass TUN  →  direct (LAN, HomeKit, Tuya, mDNS work normally)\n```\n\n---\n\n## Sources\n\n- Hiddify App: https://github.com/hiddify/hiddify-app\n- Decky Loader: https://github.com/SteamDeckHomebrew/decky-loader\n- sing-box (hiddify-core): https://github.com/SagerNet/sing-box\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenmrnngp-cloud%2Fhiddify-steam-deck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenmrnngp-cloud%2Fhiddify-steam-deck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenmrnngp-cloud%2Fhiddify-steam-deck/lists"}