https://github.com/bindreams/hole
https://github.com/bindreams/hole
Last synced: 24 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/bindreams/hole
- Owner: bindreams
- License: gpl-3.0
- Created: 2026-03-19T12:48:38.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-28T16:21:11.000Z (30 days ago)
- Last Synced: 2026-03-28T16:35:55.555Z (30 days ago)
- Language: Rust
- Size: 318 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Hole
Shadowsocks GUI with transparent proxy (TUN), system tray, and v2ray-plugin support for macOS and Windows.
## Features
- **Transparent proxy** via TUN interface — zero config for all apps, including those that ignore system proxy settings
- **SOCKS5 proxy** on port 4073 for advanced users
- **DNS leak prevention** — all DNS traffic routed through the tunnel
- **System tray** — Enable/Disable, Start at Login, Settings, Exit
- **Server import** — import from shadowsocks client config files (single and multi-server)
- **v2ray-plugin** support (built from source)
- **Logging** with daily rotation
## Architecture
Single-binary design — `hole` serves as both the Tauri GUI and the privileged daemon depending on CLI arguments:
| Mode | Privilege | Role |
| ----------------- | ------------- | ----------------------------------------------------------- |
| `hole` (no args) | User | Tauri GUI — system tray, settings window, config management |
| `hole daemon run` | Root / SYSTEM | Privileged helper — TUN, routing, shadowsocks-service |
Communication happens over IPC (Unix socket on macOS, named pipe on Windows) using HTTP/1.1 REST (JSON).
## Build
Prerequisites: Rust toolchain, Go toolchain, Node.js (for Tauri CLI and E2E tests).
```sh
# Build all crates (build.rs automatically builds v2ray-plugin from source
# and downloads wintun.dll on Windows)
cargo build --workspace
# Run GUI in dev mode
npx tauri dev
# Run all tests
cargo test --workspace
```
## Project layout
```
crates/
common/ hole-common — shared types (protocol, config, import)
daemon/ hole-daemon — privileged daemon library
gui/ hole-gui — Tauri app + CLI (binary name: "hole")
external/
v2ray-plugin/ v2ray-plugin source (git subrepo)
msi-installer/ WiX MSI installer (Python project: source, build script, tests)
ui/ Frontend HTML/CSS/JS
scripts/ Utility scripts
tests/ E2E test specs (WebDriverIO)
```
## Testing
Unit tests use the [skuld](https://github.com/bindreams/skuld) framework. Test files are siblings to their source files (`foo.rs` → `foo_tests.rs`).
```sh
cargo test --workspace # all unit tests
npm run test:e2e # E2E tests (requires release build)
```
## Emergency network reset
If routing gets into a bad state during development:
```sh
# macOS
sudo python scripts/network-reset.py
# Windows (run as Administrator)
python scripts/network-reset.py
```
## License
TBD