{"id":31533996,"url":"https://github.com/gozargah/nabzram","last_synced_at":"2025-10-05T11:42:30.317Z","repository":{"id":317448463,"uuid":"1066345050","full_name":"Gozargah/Nabzram","owner":"Gozargah","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-30T22:37:35.000Z","size":1788,"stargazers_count":15,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-01T00:23:36.635Z","etag":null,"topics":["censorship-resistant","marzban","proxy","shadowsocks","trojan","v2ray","vless","vmess","xray"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gozargah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-09-29T11:04:25.000Z","updated_at":"2025-09-30T22:37:29.000Z","dependencies_parsed_at":"2025-10-01T00:23:41.592Z","dependency_job_id":"ca0508c2-8a74-42f7-9c0b-8334bf5b5a5f","html_url":"https://github.com/Gozargah/Nabzram","commit_stats":null,"previous_names":["gozargah/nabzram"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Gozargah/Nabzram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gozargah%2FNabzram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gozargah%2FNabzram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gozargah%2FNabzram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gozargah%2FNabzram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gozargah","download_url":"https://codeload.github.com/Gozargah/Nabzram/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gozargah%2FNabzram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278266896,"owners_count":25958733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["censorship-resistant","marzban","proxy","shadowsocks","trojan","v2ray","vless","vmess","xray"],"created_at":"2025-10-04T05:16:01.417Z","updated_at":"2025-10-04T05:16:05.971Z","avatar_url":"https://github.com/Gozargah.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/icon.png\" alt=\"Nabzram\" width=\"128\"/\u003e\n\n# Nabzram\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n*A Marzban client tool for connecting to Marzban subscriptions, born out of pure boredom and built with whatever tech stack was lying around* 🤷🏻‍♂️\n\n\u003c/div\u003e\n\n\u003e This entire project, including the logo, components, app architecture, and even this README you're reading right now, was crafted by AI. Well, except the name \"Nabzram\" - that was my brilliant idea! 😮‍💨 I was bored one day, had some subscriptions to use, and thought \"why not?\" So here we are - a desktop app that actually does exactly what it needs to do, and it works!\n\nA modern GUI application for managing and connecting to **Marzban subscription servers**. Built with Python and React, wrapped in a native desktop application using pywebview.\n\n\u003e **Important**: This app is made specifically for Marzban subscriptions. It runs Xray-core and exposes SOCKS/HTTP proxies to your system. **System-wide proxy configuration is now supported** - TUN interface is not yet implemented.\n\n![Nabzram](https://img.shields.io/github/v/release/gozargah/nabzram?label=version\u0026color=blue)\n![Downloads](https://img.shields.io/github/downloads/gozargah/nabzram/total?label=downloads\u0026color=green)\n![Python](https://img.shields.io/badge/python-3.12+-green)\n![License](https://img.shields.io/badge/license-GPL--3.0-blue)\n\n## Download\n\n**Ready to use:** Download the latest release from [GitHub Releases](https://github.com/gozargah/nabzram/releases)  \nNo installation required – just run the executable for your platform!\n\n### Direct Download Links\n\n| Platform / File | Download |\n|-----------------|----------|\n| **Linux (64-bit)** | [nabzram-linux-x86_64](https://github.com/gozargah/nabzram/releases/latest/download/nabzram-linux-x86_64) |\n| **Linux (ARM 64-bit)** | [nabzram-linux-arm64](https://github.com/gozargah/nabzram/releases/latest/download/nabzram-linux-arm64) |\n| **macOS (64-bit)** | [nabzram-macos-x86_64.zip](https://github.com/gozargah/nabzram/releases/latest/download/nabzram-macos-x86_64.zip) |\n| **macOS (ARM 64-bit)** | [nabzram-macos-arm64.zip](https://github.com/gozargah/nabzram/releases/latest/download/nabzram-macos-arm64.zip) |\n| **Windows (64-bit)** | [nabzram-windows-x86_64.exe](https://github.com/gozargah/nabzram/releases/latest/download/nabzram-windows-x86_64.exe) |\n| **Debian/Ubuntu (64-bit)** | [nabzram_25.10.0117_amd64.deb](https://github.com/gozargah/nabzram/releases/latest/download/nabzram_25.10.0117_amd64.deb) |\n| **Debian/Ubuntu (ARM 64-bit)** | [nabzram_25.10.0117_arm64.deb](https://github.com/gozargah/nabzram/releases/latest/download/nabzram_25.10.0117_arm64.deb) |\n\n## Features\n\n- **📱 Modern UI**: Clean, responsive interface with dark theme\n- **🔧 System Tray**: Minimize to system tray with quick access\n- **🔗 Marzban Integration**: Add and connect to Marzban subscription servers\n- **🌐 System-wide Proxy**: Automatically configure proxy to your system\n- **🎨 Customizable Settings**: Configure Xray paths, ports, and appearance preferences\n- **🖥️ Cross-Platform**: Native desktop app supporting Windows, macOS, and Linux\n\n## Screenshots\n\n\u003cdiv style=\"overflow-x: auto; white-space: nowrap;\"\u003e\n  \u003cimg src=\"screenshots/0.png\" width=\"300\" style=\"display: inline-block; margin-right: 10px;\"/\u003e\n  \u003cimg src=\"screenshots/1.png\" width=\"300\" style=\"display: inline-block; margin-right: 10px;\"/\u003e\n  \u003cimg src=\"screenshots/2.png\" width=\"300\" style=\"display: inline-block; margin-right: 10px;\"/\u003e\n  \u003cimg src=\"screenshots/3.png\" width=\"300\" style=\"display: inline-block; margin-right: 10px;\"/\u003e\n  \u003cimg src=\"screenshots/4.png\" width=\"300\" style=\"display: inline-block; margin-right: 10px;\"/\u003e\n  \u003cimg src=\"screenshots/5.png\" width=\"300\" style=\"display: inline-block; margin-right: 10px;\"/\u003e\n\u003c/div\u003e\n\n## Build from Source\n\n### Prerequisites\n\n- **Python 3.12+**\n- **UV**: For managing Python versions and dependencies\n- **Xray-core**: Optional - app will download it for you if not found\n- **Bun**: For frontend development (recommended) or Node.js\n\n**Supported Platforms**: Windows, macOS, and Linux\n\n### System Dependencies\n\n#### Linux (Ubuntu/Debian)\n```bash\nsudo apt-get update\nsudo apt-get install -y \\\n  pkg-config build-essential python3-dev \\\n  libcairo2-dev libgirepository1.0-dev \\\n  libgtk-3-dev libwebkit2gtk-4.1-dev\n```\n\n#### Windows\n- No additional system dependencies required\n- Xray-core will be automatically downloaded if not found\n\n#### macOS\n- No additional system dependencies required\n- Xray-core will be automatically downloaded if not found\n\n### Install Xray-core (Optional)\n\nThe app can automatically download Xray-core if not found, but you can also install it manually:\n\n#### Linux\n```bash\n# Download and install Xray-core\nbash \u003c(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)\n```\n\n#### Windows\n- Download from [Xray releases](https://github.com/XTLS/Xray-core/releases)\n- Or let Nabzram download it automatically\n\n#### macOS\n```bash\n# Using Homebrew\nbrew install xray\n\n# Or download manually from releases\n```\n\n**Note**: If Xray-core is not installed, the app will prompt you to download it automatically on first run.\n\n### Install UV\n\nFollow instructions at [astral.sh/uv](https://astral.sh/uv/)\n\n### Python Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/gozargah/nabzram.git\n   cd nabzram\n   ```\n\n2. **Install Python dependencies**\n   ```bash\n   uv sync\n   ```\n\n3. **Run the application**\n   ```bash\n   uv run main.py\n   ```\n\n## Development\n\n### Frontend Development\n\nThe frontend is built with React, TypeScript, and Vite:\n\n```bash\ncd ui\nbun install\nbun run dev\n```\n\nThe development server will start on `http://localhost:5173` and automatically reload on changes.\n\n### Backend Development\n\nThe backend uses a modular architecture with operations and services:\n\n```bash\n# Run the main application\nuv run main.py\n\n# The application uses pywebview to create a native desktop window\n# No separate server process needed - everything runs in the main process\n```\n\n**Note**: The application uses pywebview's built-in HTTP server for the frontend-backend communication.\n\n### Building Executable\n\nBuild a standalone executable using Nuitka:\n\n```bash\nuv run build.py\n```\n\nThis will:\n1. Build the React frontend using Vite\n2. Compile the Python application with Nuitka\n3. Create a single executable file in the `dist/` directory\n\nThe build script automatically handles:\n- Frontend dependency installation and building\n- Nuitka installation if not present\n- Platform-specific optimizations (Windows, macOS, Linux)\n- Icon and asset bundling\n\n## Configuration\n\n### Environment Variables\n\nCopy `env.example` to `.env` and modify as needed:\n\n```bash\ncp env.example .env\n```\n\nAvailable options:\n- `DATABASE_PATH`: Database file location (default: user data directory)\n- `DEBUG`: Enable debug mode (default: false)\n\n### Settings\n\nConfigure the application through the Settings modal:\n- **Xray Binary Path**: Custom path to Xray executable\n- **Assets Folder**: Xray assets directory\n- **SOCKS Port**: Default SOCKS proxy port\n- **HTTP Port**: Default HTTP proxy port\n\n## Usage\n\n### Adding Marzban Subscriptions\n\n1. Click the **\"+\"** button to add a new subscription\n2. Enter a name and your Marzban subscription URL (must support `/v2ray-json` endpoint)\n3. The app will automatically fetch and parse server configurations\n4. Servers will appear in the subscription list\n\n### Connecting to Servers\n\n1. Select a subscription to view its servers\n2. Click on a server to connect\n3. Monitor connection status and logs\n4. Use the disconnect button to stop the connection\n\n**Note**: Connections expose SOCKS and HTTP proxies to your system. You'll need to configure your applications to use these proxies manually - no system-wide proxy or TUN interface is configured.\n\n## Architecture\n\n### Backend (Python)\n- **PyWebview**: Desktop application wrapper with built-in HTTP server\n- **TinyDB**: Local database for subscriptions and settings\n- **Xray-core**: Proxy protocol implementation\n\n### Frontend (React)\n- **React 19**: UI framework\n- **TypeScript**: Type safety\n- **Vite**: Build tool and dev server\n- **Tailwind CSS**: Styling (via CDN)\n\n### Project Structure\n```\napp/\n├── gui/           # GUI management and window APIs\n├── ops/           # Core operations (logs, servers, settings, etc.)\n├── services/      # Business logic services\n├── models/        # Data models and schemas\n└── database/      # Database management\n```\n\n## Supported Protocols\n\n- **VMess**: V2Ray protocol\n- **VLESS**: V2Ray protocol variant\n- **Trojan**: Trojan protocol\n- **Shadowsocks**: Shadowsocks protocol\n- **HTTP/HTTPS**: HTTP proxy\n- **SOCKS**: SOCKS proxy\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the [LICENSE](LICENSE) file for full terms.\n\n- No warranty is provided, express or implied (see Sections 15–16).\n- If you distribute modified versions, you must release the source code under GPL-3.0.\n- Please include attribution by mentioning that your project is a fork of `Nabzram` and link back to this repository.\n\n## Acknowledgments\n\n- [Xray-core](https://github.com/XTLS/Xray-core) - Proxy protocol implementation\n- [React](https://reactjs.org/) - UI library\n- [PyWebview](https://github.com/r0x0r/pywebview) - Desktop wrapper\n- [TinyDB](https://tinydb.readthedocs.io/) - Lightweight database\n- [Nuitka](https://nuitka.net/) - Python compiler for standalone executables\n\n## API Documentation\n\nFor detailed API documentation, see [docs/API.md](docs/API.md). This document covers all available methods exposed to the frontend via `window.pywebview.api`.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/Gozargah/Nabzram/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/Gozargah/Nabzram/discussions)\n- **Documentation**: [Wiki](https://github.com/Gozargah/Nabzram/wiki)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgozargah%2Fnabzram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgozargah%2Fnabzram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgozargah%2Fnabzram/lists"}