localstream 1.0.9
Python CLI client for slipstream-rust DNS tunnel
License: Apache-2.0
Requires Python: >=3.11
Keywords: dns, tunnel, vpn, slipstream, cli

# 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)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/localstream?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/localstream)

**A Python client for [slipstream-rust](https://github.com/Mygod/slipstream-rust), [Ping Tunnel](https://github.com/esrrhs/pingtunnel) and [DNSTT](https://github.com/bugfloyd/dnstt-deploy), [Sing-Box](https://github.com/SagerNet/sing-box) and **DoH**. designed to bypass censorship and secure your connection with more than 5 methods!.**

</div>

---

## 📖 Overview

**LocalStream** simplifies the usage of complex DNS tunneling. It wraps the powerful `slipstream-rust`, `PingTunnel`, `DNSTT`, `Sing-Box` and `DoH` 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.
- **DNS Checker**: you can use the DNS Checker in both CLI and GUI to check if your DNS works or not.
- **Multi-Muthod Support**: this tool supports SlipStream/DNSTT/PingTunnel Configs in both CLI and GUI

## 📥 Installation

### For End Users
Download the latest [**Setup/Portable**](https://github.com/ShiftGlory/LocalStream/releases) 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://github.com/ShiftGlory/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>