localstream 1.0.4

Python CLI client for slipstream-rust DNS tunnel

LocalStream

A high-performance, resilient Python CLI client for the slipstream-rust DNS tunnel.

---

📖 Overview

LocalStream simplifies the usage of standard DNS tunneling. It provides a robust, menu-driven interface to manage connections, supporting both System-wide VPN (via tun2proxy) and SOCKS5 Proxy modes. Whether you need to secure your entire system or just specific applications, LocalStream handles the complexity for you.

✨ Features

• 🚀 High Performance: Optimized for Windows and Linux with minimal resource overhead.
• 🛡️ VPN Mode: Full system-wide traffic tunneling (requires Administrator privileges).
• 🔌 Proxy Mode: Flexible SOCKS5 proxy on local port 5201 (default).
• 🔄 Auto-Reconnect: Intelligent connection watchdog that keeps you online.
• 📦 Smart Dependency Management: Automatically downloads and manages slipstream-client, tun2proxy, and wintun drivers.

📥 Installation

Install easily via pip:

pip install localstream

For development (editable mode):

pip install -e .

🚀 Usage

To start the application, simply run:

LocalStream

⚠️ Important: To use VPN Mode, you must run with elevated privileges:

• Windows: Run terminal as Administrator
• Linux: The app will automatically request sudo when needed

🎮 Controls

• Menu Navigation: Follow the on-screen prompts (Enter numbers 1, 2, 3...).
• Disconnect: Press Ctrl+C to safely stop the connection and return to the menu.
• Force Restart: Press Ctrl+D to force a reconnection attempt.

⚙️ Configuration

Configuration is automatically created at first run in ~/.localstream/config.json. You can also edit it via the CLI menu.

{
  "server_ip": "203.0.113.2",
  "server_port": 53,
  "local_port": 5201,
  "domain": "s.example.com"
}

🛠️ Requirements

• Operating System: Windows 10/11 or Linux (Ubuntu, Debian, Fedora, Arch...)
• Runtime: Python 3.13 or higher
• Permissions: Administrator/sudo rights (only for VPN mode)

🤝 Contributing

We welcome contributions! Please check out our CONTRIBUTING.md guide for guidelines on how to proceed.

🔒 Security

We take security seriously. Please review our SECURITY.md policy for reporting vulnerabilities.

📄 License

This project is licensed under the Apache-2.0 License. See the LICENSE file for full details.

---

Built with ❤️ by the LocalStream Team