Metadata-Version: 2.4
Name: localstream
Version: 1.0.8
Summary: Python CLI client for slipstream-rust DNS tunnel
Author: LocalStream Team
License: Apache-2.0
Keywords: dns,tunnel,vpn,slipstream,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Proxy Servers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: cryptography>=42.0.0
Provides-Extra: gui
Requires-Dist: fastapi>=0.104.0; extra == "gui"
Requires-Dist: uvicorn>=0.24.0; extra == "gui"
Requires-Dist: pydantic>=2.5.0; extra == "gui"
Dynamic: license-file

# LocalStream

<div align="center">

![Version](https://img.shields.io/pypi/v/localstream?style=for-the-badge&logo=pypi&logoColor=white)
![Python](https://img.shields.io/badge/python-3.11%2B-FFE873?style=for-the-badge&logo=python&logoColor=white)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-0078D6?style=for-the-badge&logo=windows&logoColor=white)
![License](https://img.shields.io/badge/license-Apache%202.0-success?style=for-the-badge)

**A robust Python client for the [slipstream-rust](https://github.com/Mygod/slipstream-rust) DNS tunnel, designed to bypass censorship and secure your connection.**

</div>

---

## 📖 Overview

**LocalStream** simplifies the usage of complex DNS tunneling. It wraps the powerful `slipstream-rust` into a user-friendly interface that manages dependencies, connectivity, and routing automatically.

Designed specifically to operate in restricted network environments, LocalStream supports advanced features like **TLS Fragmentation** and **System-wide VPN** (via `tun2proxy`). Whether you need to secure your entire system or just provide a SOCKS5 proxy for specific applications, LocalStream offers a stable and resilient solution.

## ✨ Features

- **Dual Operation Modes**: Switch effortlessly between **VPN Mode** (full device tunneling) and **Proxy Mode** (SOCKS5).
- **Censorship Circumvention**: Optimized for users in high-censorship regions (e.g., Iran), with support for TLS fragmentation and custom DNS resolvers.
- **Automated Management**: Automatically downloads and configures necessary binaries (`slipstream-client`, `tun2proxy`, `wintun`).
- **Resilient Connectivity**:
    - **Auto-Reconnect**: Intelligent watchdog monitors your connection and reconnects instantly if it drops.
    - **Auto-Restart**: Optional scheduled restarts to maintain long-term stability.
- **Config Import/Export**: Securely share configuration profiles encrypted with `.local` files.
- **Modern Interface**: Available as a robust CLI or a modern GUI application.

## 📥 Installation

### For End Users
Download the latest [**Setup.exe**](https://gitlab.com/GloryMajor/LocalStream/releases/latest) from our releases page and run the installer.

### For Developers
Install via pip:

```bash
pip install localstream
```

Or for local development:

```bash
git clone https://gitlab.com/GloryMajor/LocalStream.git
cd LocalStream
pip install -e .
```

## 🚀 Usage

### GUI Application
Launch **LocalStream** from your Start Menu or Desktop shortcut.
1. Add your server configuration or import a profile.
2. Select **VPN Mode** or **Proxy Mode**.
3. Click **Connect**.

### Command Line Interface (CLI)
Run the application from your terminal:

```bash
LocalStream
```

Follow the interactive menu prompts to configure your server and start the connection.

> **⚠️ Important**: To use **VPN Mode**, you must run the application with elevated privileges:
> - **Windows**: Run as **Administrator**
> - **Linux**: Run with `sudo`

## ⚙️ Configuration

Your configuration is stored in `~/.localstream/config.json`. You can edit it via the application or manually:

```json
{
  "server_ip": "203.0.113.2",
  "server_port": 53,
  "local_port": 5201,
  "domain": "s.example.com",
  "keep_alive_interval": 200,
  "congestion_control": "bbr",
  "enable_fragmentation": false,
  "auto_restart_minutes": 0
}
```

## 🛠️ Requirements

- **Operating System**: Windows 10/11 or Linux (Ubuntu, Debian, Fedora, Arch, etc.)
- **Python**: 3.11 or higher (for source installation)
- **Privileges**: Administrator/sudo rights (required for VPN mode)

## 🤝 Contributing

We welcome contributions! Please check out our [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on how to get involved.

## 🔒 Security

We take security seriously. Please review our [SECURITY.md](SECURITY.md) policy for reporting vulnerabilities.

## 📄 License

This project is licensed under the **Apache-2.0 License**. See the [LICENSE](LICENSE) file for full details.

---

<div align="center">
    <i>Built with ❤️ by GloryMajor</i>
</div>
