Metadata-Version: 2.4
Name: homegate-p2p
Version: 1.0.0
Summary: Free, open-source P2P tunnel with TCP & UDP support. Self-hosted alternative to ngrok.
Author-email: Homegate <hello@homegate.io>
License: MIT
Project-URL: Homepage, https://homegate.io
Project-URL: Repository, https://github.com/homegate/homegate-p2p
Project-URL: Documentation, https://github.com/homegate/homegate-p2p#readme
Project-URL: Bug Tracker, https://github.com/homegate/homegate-p2p/issues
Keywords: tunnel,p2p,ngrok,reticulum,self-hosted,vpn,tcp,udp,game-server,ollama,ai,encrypted,peer-to-peer,reverse-tunnel
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: System :: Networking
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rns>=0.7.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Homegate P2P

**Free, open-source, peer-to-peer tunnel with full TCP & UDP support.**

Connect two machines directly — encrypted, no account, no subscription, no intermediary server.
Built on [Reticulum](https://reticulum.network) encrypted transport.

![Platform](https://img.shields.io/badge/platform-Linux-blue)
![Platform](https://img.shields.io/badge/platform-Windows-0078D4?logo=windows)
![Platform](https://img.shields.io/badge/platform-macOS-blue?logo=apple)
![License](https://img.shields.io/badge/license-MIT-green)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![PyPI](https://img.shields.io/pypi/v/homegate-p2p)

> A free, self-hosted alternative to ngrok — with UDP support for game servers and AI model sharing.

---

## How it actually works

Homegate P2P connects two machines directly using the Reticulum protocol. Each side gets a **hash** — a permanent cryptographic identity. You share your hash, the other side connects to it.

**For the connection to work, at least one of the following must be true:**

- **You have a public IPv6 address** — most modern ISPs provide one for free, no extra cost, just check if you have it
- **Both sides connect to a common Reticulum relay node** — free public nodes maintained by the Reticulum community

Neither requires buying a static IP or configuring your router.
But this is peer-to-peer — there's no magic. *Someone* has to be reachable.

> Want friends to connect using a simple URL like `yourname.homegate.io` without installing anything? That's what **[Homegate Pro](https://homegate.io)** is for — it uses a managed VPS as the relay and exposes your service to the web over HTTPS.

---

## Use cases

**Share local AI models**
Run Ollama, LM Studio, Stable Diffusion, or ComfyUI on your GPU and share it directly with a colleague — encrypted, no cloud, no API costs.

**Host game servers from home**
Self-host Minecraft, Valheim, Counter-Strike, or ARK. Full UDP support — something Cloudflare Tunnel doesn't offer.

**Share a local web app or development server**
Expose any HTTP service instantly — no ngrok account needed.

**Remote access between your own devices**
Connect to a home server, Raspberry Pi, or camera from anywhere — without a VPN or static IP.

| Use case | Protocol | Port |
|---|---|---|
| Minecraft server | UDP | 25565 |
| Valheim server | UDP | 2456 |
| Counter-Strike | UDP | 27015 |
| Ollama (AI models) | TCP | 11434 |
| Stable Diffusion / ComfyUI | TCP | 7860 |
| LM Studio | TCP | 8080 |
| Open WebUI | TCP | 3000 |
| Any web app or API | TCP | any |

---

## Platform support

| Platform | Status |
|---|---|
| Linux | ✅ Available |
| Windows | ✅ Available |
| macOS | ✅ Available |

---

## Requirements

- Python 3.10+
- tkinter — for the optional GUI
  - Linux: `sudo apt install python3-tk`
  - macOS: `brew install python-tk`
  - Windows: included with the official Python installer (check "tcl/tk and IDLE" during setup)

---

## Installation

### Option A — pip (recommended)

```bash
pip install homegate-p2p
```

That's it. The `homegate-p2p` command is now available globally.

> **GUI note:** The GUI requires tkinter, which can't be installed via pip. If you want the GUI, install tkinter for your platform first (see requirements above), then `homegate-p2p gui` will work automatically.

### Option B — installer scripts

**Linux:**

```bash
tar -xzf homegate-p2p-linux.tar.gz
cd homegate-p2p-linux
chmod +x install.sh
./install.sh
```

**Windows:**

1. Download and extract `homegate-p2p-windows.zip`
2. Double-click `install.bat`
3. Allow the UAC dialog — needed for the firewall rule
4. Restart PowerShell or Command Prompt

**macOS:**

```bash
tar -xzf homegate-p2p-mac.tar.gz
cd homegate-p2p-mac
chmod +x install.sh
./install.sh
```

**If `install.bat` crashes on Windows**, see [Windows manual install](#windows-manual-install) below.

---

## Windows manual install

Open **PowerShell as Administrator**:

```powershell
cd D:\path\to\homegate-p2p-windows

python -m venv venv
venv\Scripts\pip install -r requirements.txt

@"
@echo off
cd /d "$PWD"
"$PWD\venv\Scripts\python" "$PWD\homegate-p2p.py" %*
"@ | Out-File -FilePath "homegate-p2p.bat" -Encoding ascii

$current = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", "$PWD;$current", "User")
$env:PATH = "$PWD;$env:PATH"

netsh advfirewall firewall add rule name="Homegate P2P" dir=in action=allow protocol=TCP localport=4242
netsh advfirewall firewall add rule name="Homegate P2P" dir=in action=allow protocol=UDP localport=4242
```

---

## Quick start

```bash
# 1. Start the background engine (REQUIRED before anything else)
homegate-p2p daemon

# 2. Host side — expose a local service
homegate-p2p host --port 25565 --protocol UDP
# → prints your hash, share it with the other side

# 3. Client side — connect to the host
homegate-p2p daemon
homegate-p2p connect --hash <hash> --port 25565
# → connect your game/app to 127.0.0.1:25565
```

---

## Commands

```
homegate-p2p daemon              Start the background engine
homegate-p2p host                Expose a local service
homegate-p2p connect             Connect to a remote service
homegate-p2p status              Show current status
homegate-p2p logs                Stream live logs
homegate-p2p stop                Stop current session
homegate-p2p stop --daemon       Stop the engine entirely
homegate-p2p gui                 Launch the optional GUI
homegate-p2p help [command]      Show help for any command
```

---

## GUI (optional)

The daemon must be running before launching the GUI:

```bash
homegate-p2p daemon
homegate-p2p gui
```

The GUI does not manage the daemon — it only controls it. If you close the GUI, the daemon keeps running.

The **Network** tab shows your detected public IPv6 and generates the exact config block the other side needs to paste into their Reticulum config.

---

## Network modes

### Option 1 — Public IPv6 (direct connection)

Check if you have a public IPv6:

```bash
# Linux / macOS
curl -6 https://api6.ipify.org

# Windows (PowerShell)
(Invoke-WebRequest -Uri "https://api6.ipify.org" -UseBasicParsing).Content
```

If it returns an address not starting with `fc` or `fd`, you have one.

The **client** must add a config block pointing to the host's IPv6, under `[interfaces]` in their Reticulum config:

```
[[Rafa]]
  type = TCPClientInterface
  enabled = yes
  target_host = [2800:2540:3110:265:235:2cb1:5b29:1c76]
  target_port = 4242
```

> **Important:** Use square brackets around the IPv6 address.

Reticulum config file location:
- Linux / macOS: `~/.homegate-p2p/reticulum/config`
- Windows: `%APPDATA%\Homegate-P2P\reticulum\config`

After editing the config, **restart the daemon**:

```bash
homegate-p2p stop --daemon
homegate-p2p daemon
```

### Option 2 — Public Reticulum relay nodes

If neither side has a public IPv6, both add the same relay to their Reticulum config:

```
[[BetweenTheBorders]]
  type = TCPClientInterface
  enabled = yes
  target_host = reticulum.betweentheborders.com
  target_port = 4242

[[Sydney]]
  type = TCPClientInterface
  enabled = yes
  target_host = sydney.reticulum.au
  target_port = 4242
```

---

## Real-world examples

### Sharing Ollama (local AI models)

**Host side:**

```bash
# Ollama must listen on all interfaces, not just localhost
OLLAMA_HOST=0.0.0.0 ollama serve

# Or permanently via systemd:
# sudo systemctl edit ollama
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0"
# sudo systemctl restart ollama

homegate-p2p daemon
homegate-p2p host --port 11434 --protocol TCP
```

**Client side:**

```
homegate-p2p daemon
homegate-p2p connect --hash <hash> --port 11434 --protocol TCP
```

Then use the Ollama API at `http://127.0.0.1:11434`:

```powershell
# List available models
(Invoke-WebRequest -Uri "http://127.0.0.1:11434/api/tags" -UseBasicParsing).Content

# Generate text
$body = '{"model":"mistral:latest","prompt":"hello","stream":false}'
(Invoke-WebRequest -Uri "http://127.0.0.1:11434/api/generate" -Method POST -Body $body -ContentType "application/json" -UseBasicParsing).Content
```

Or use [Open WebUI](https://github.com/open-webui/open-webui) locally pointing to `http://127.0.0.1:11434`.

---

### Sharing a local web page or app

**Host side:**

```bash
mkdir /tmp/mysite
cat > /tmp/mysite/index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Homegate P2P Test</title>
</head>
<body>
  <h1>Hello from Homegate P2P!</h1>
</body>
</html>
EOF

cd /tmp/mysite
python3 -m http.server 8080

# In another terminal:
homegate-p2p daemon
homegate-p2p host --port 8080 --protocol TCP
```

**Client side:**

```
homegate-p2p connect --hash <hash> --port 8080 --protocol TCP
```

Open `http://127.0.0.1:8080` in the browser.

> **Tip:** Always add `<meta charset="UTF-8">` to avoid garbled characters on the client side.

---

### Hosting a game server (Minecraft)

**Host side:**

```bash
homegate-p2p daemon
homegate-p2p host --port 25565 --protocol UDP
```

**Client side:**

```
homegate-p2p connect --hash <hash> --port 25565 --protocol UDP
```

Connect in Minecraft to `127.0.0.1:25565`.

---

## Architecture

```
homegate-p2p <command>        ← CLI entry point
        │
        ▼
  DaemonClient                ← JSON over localhost:9877
        │
        ▼
    daemon.py                 ← Reticulum engine + local API
    ├── host.py               ← host mode (multiplexed TCP, multiple clients)
    └── connector.py          ← connect mode (multiplexed TCP, multiple connections)

  gui.py (optional)           ← talks to daemon via DaemonClient
```

TCP connections are multiplexed over a single Reticulum link — each connection has a unique ID so parallel requests (browser loading a page with CSS, JS and images) all work simultaneously.

---

## Troubleshooting

### Full reset — when nothing else works

If things are in a broken state, kill everything and start clean:

```bash
# Linux / macOS
pkill -f daemon.py
pkill -f homegate-p2p
sleep 2
homegate-p2p daemon

# Windows
taskkill /F /IM python.exe /T
homegate-p2p daemon
```

---

### Daemon not starting

```bash
homegate-p2p daemon --foreground   # see all errors in real time
homegate-p2p logs                  # check log file
```

**Port 9877 already in use** — a previous daemon didn't close cleanly:

```bash
# Linux / macOS
pkill -f daemon.py
sleep 1
homegate-p2p daemon

# Windows
for /f "tokens=5" %p in ('netstat -ano ^| findstr ":9877"') do taskkill /F /PID %p
homegate-p2p daemon
```

---

### Host not found when connecting

1. Make sure the client's Reticulum config has the host's IPv6 under `[interfaces]`
2. After editing the config, **restart the daemon** — config is only read at startup
3. Wait up to 30 seconds — Reticulum needs time to propagate announcements
4. Test if the host's port is reachable:

```bash
# Linux / macOS
nc -zv HOST_IPV6 4242

# Windows
Test-NetConnection -ComputerName "HOST_IPV6" -Port 4242
```

---

### Reticulum config gets overwritten

The current version only generates the config if the file doesn't exist yet. If you're on an older version, reinstall.

On Windows — save your config before reinstalling:

```powershell
copy "%APPDATA%\Homegate-P2P\reticulum\config" "%TEMP%\rns_backup.txt"
install.bat
copy "%TEMP%\rns_backup.txt" "%APPDATA%\Homegate-P2P\reticulum\config"
```

---

### Ollama: connection refused

Ollama only accepts connections from `127.0.0.1` by default. Set:

```bash
OLLAMA_HOST=0.0.0.0 ollama serve
```

Or permanently via systemd:

```bash
sudo systemctl edit ollama
# Add:
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0"
sudo systemctl restart ollama
```

---

### Web pages show garbled characters

Add `<meta charset="UTF-8">` inside `<head>` in your HTML.

---

### Logs show encoding errors on Windows

Update to the latest version — `homegate-p2p logs` now uses `errors="replace"`.

---

### Port already in use

```bash
homegate-p2p stop
homegate-p2p host --port 8081
```

---

### GUI not available

```bash
# Linux
sudo apt install python3-tk

# macOS
brew install python-tk

# Windows — reinstall Python from https://www.python.org/downloads/
# Check "tcl/tk and IDLE" during installation
```

---

## Security & privacy

- **End-to-end encrypted** — Reticulum encrypts all traffic before it leaves your machine
- **No account, no telemetry** — nothing phoning home
- **No Homegate servers involved** — pure P2P
- **Permanent identity** — your hash is derived from a local key pair at `~/.homegate-p2p/identity`
- **Open source** — MIT licensed, fully auditable

---

## Compared to alternatives

| | Homegate P2P | ngrok free | Cloudflare Tunnel | Tailscale |
|---|---|---|---|---|
| Price | **Free** | Free (limited) | Free | Free (limited) |
| UDP support | ✅ | ❌ | ❌ | ✅ |
| No account required | ✅ | ❌ | ❌ | ❌ |
| No central server | ✅ | ❌ | ❌ | ❌ |
| Fully self-hostable | ✅ | ❌ | ❌ | Partial |
| Public URL | ❌ | ✅ | ✅ | ❌ |
| Both sides need install | Yes | No | No | Yes |
| Game server (UDP) support | ✅ | ❌ | ❌ | ✅ |
| Multiplexed TCP | ✅ | ✅ | ✅ | ✅ |
| Open source | ✅ | ❌ | ❌ | Partial |

**Homegate P2P is best when:**
Both sides are technical users. You want zero dependency on any external company. You need UDP. You don't want an account.

**[Homegate Pro](https://homegate.io) ($5/mo) is better when:**
You want a permanent public URL (`yourname.homegate.io`) so the other side connects without installing anything — just a URL, with HTTPS included.

---

## File locations

| Path | Description |
|---|---|
| `~/.homegate-p2p/config.json` | App configuration (Linux/macOS) |
| `~/.homegate-p2p/identity` | Your permanent cryptographic identity (Linux/macOS) |
| `~/.homegate-p2p/daemon.log` | Daemon logs (Linux/macOS) |
| `~/.homegate-p2p/reticulum/` | Reticulum config (Linux/macOS) |
| `%APPDATA%\Homegate-P2P\` | All app files (Windows) |

---

## License

MIT

---

## Contact

Built by [Rafael Matias Pinera](https://www.linkedin.com/in/rafael-matias-pinera/) — feel free to reach out on LinkedIn for questions, feedback, or collaboration.

---

## Related

- [Homegate Pro](https://homegate.io) — managed tunnel with permanent public URL, no install for the other side
- [Reticulum Network Stack](https://reticulum.network) — the encrypted transport layer powering this project
- [NomadNet](https://github.com/markqvist/NomadNet) — another app built on Reticulum
