Iron Tunnel

Secure AI Gateway — Share your local AI with friends without exposing your network.

---

What is this?

Iron Tunnel lets you securely share your local AI (Oobabooga, LM Studio, llama.cpp, etc.) with specific people over the internet — without port forwarding, without exposing your IP, and without giving everyone access.

The problem: You have an AI running locally. You want your friend to use it. But you don't want to expose your home IP or let random people access it.

The solution: Iron Tunnel creates a secure gateway with generated client executables. Only people with YOUR specific client exe AND a one-time install code can access YOUR specific host.

---

How It Works

YOU (Host)                              FRIEND (Client)
─────────────────────────────────────────────────────────────
1. Run iron_host.py
2. generate "Alex Laptop"
   → Creates IronClient_Alex.exe
   → Creates install code: K7M2-X9R4-P3N8

3. Send exe + code to Alex ──────────► 4. Run exe, enter code
                                        5. Open tunnel URL in browser
                                        
6. See: "Alex wants to connect"    ◄─── 6. Client auto-authenticates
   Code: ABCD1234
   
7. Verify code, type: approve Alex ───► 8. VoxAI chat interface loads

Done. Alex can now chat with your AI.

---

Features

• 🔐 Host-Bound Clients — Generated exes only work with YOUR host
• 🎫 One-Time Install Codes — Like game CD keys, use once then consumed
• 👁️ Session Verification — Pairing codes for each browser session
• ⚡ Instant Revocation — Kill any client exe remotely
• 🚫 Invisible to Scanners — No client = redirect to Google
• 🔒 No Port Forwarding — Uses Ngrok tunnel

---

Quick Start

1. Install

git clone https://github.com/yourusername/iron-tunnel.git
cd iron-tunnel
pip install -r requirements.txt

2. Run Host

python iron_host.py

Or on Windows, double-click start.bat

First run will:

• Generate your unique Host ID
• Ask for your Ngrok auth token
• Open the tunnel

3. Generate a Client

Admin> generate "Alex Laptop"

✓ Client generated!
  Name:         Alex Laptop
  Client ID:    CLT-7F3A-X9K2-M4B8
  Install Code: K7M2-X9R4-P3N8
  Exe:          IronClient_Alex_Laptop_7F3A.exe

Give the .exe and install code to Alex.

4. Client Setup

Alex needs:

• The .exe file you generated
• The install code
• Npcap installed (Windows)
• Run as administrator

Enter Install Code: K7M2-X9R4-P3N8
✓ Activation successful!

[READY] Monitoring for tunnel access...
Open the tunnel URL in your browser.

5. Approve Session

When Alex opens the tunnel URL:

Admin> 
[!] CLIENT REQUESTING SESSION
    Name: Alex Laptop
    ID:   CLT-7F3A-X9K2-M4B8
    Code: ABCD1234

Admin> approve "Alex"
✓ Session approved for Alex Laptop (24h)

---

Configuration

Changing the Port

By default, IronGate runs on port 8000. To change this:

1. Open host_config.json in this directory.
2. Add or update the "port" field:

   {
       "port": 8080,
       ...
   }

3. Restart iron_host.py.

---

Admin Commands

Command	Description
generate "name"	Create new client exe + install code
list	Show all clients and their status
sessions	Show active browser sessions
approve "name"	Approve a pending session request
kick "name"	End session (client must re-authenticate)
revoke "name"	Permanently disable a client exe
lockdown	Emergency kill switch — block ALL connections
export	Backup your host identity
status	Show overview
clear	Clear screen
help	Show commands

---

Requirements

Host

• Python 3.10+
• Ngrok account (free tier works)
• Local AI backend (Oobabooga, LM Studio, etc.)

Client

• Windows + Npcap
• Run as administrator
• Install code from host

---

AI Backend Setup

Edit ai_bridge.py to point to your AI:

# Oobabooga
AI_URL = "http://127.0.0.1:5000/v1/chat/completions"

# LM Studio
AI_URL = "http://127.0.0.1:1234/v1/chat/completions"

# llama.cpp
AI_URL = "http://127.0.0.1:8080/v1/chat/completions"

Any OpenAI-compatible API will work.

---

Security Model

What's Protected

Threat	Protection
Random scanners	See nothing, redirected to Google
No client installed	Redirected to Google
Wrong client exe	Rejected (bound to different host)
Stolen exe without code	Can't activate
Compromised client	Revoke instantly
Session hijacking	Pairing codes verify each session

What's NOT Protected

• Attacker with both exe AND unused install code
• Compromised host machine
• Physical access to activated client

Best Practices

1. Send exe and install code separately — different channels
2. Verify pairing codes — don't just auto-approve
3. Revoke when not needed — don't leave old clients active
4. Backup host identity — use export command
5. Use short sessions — adjust SESSION_DURATION_HOURS

---

File Structure

iron-tunnel/
├── iron_host.py           # Main application
├── ai_bridge.py           # AI backend connector  
├── requirements.txt       # Dependencies
├── start.bat              # Windows launcher
├── README.md              # This file
├── TECHNICAL.md           # Detailed documentation
│
├── host_identity.key      # [Generated] Your host ID (backup this!)
├── host_config.json       # [Generated] Settings
├── clients.json           # [Generated] Client database
│
├── exports/               # [Generated] Client exe files
├── templates/             # [Auto-created] Web templates
└── logs/                  # [Generated] Session logs

---

Troubleshooting

"Ngrok Conflict" / Tunnel already online

IronGate automatically attempts to kill old processes on startup. If you still see this error:

1. Close the IronGate window.
2. Open a terminal and run: taskkill /F /IM ngrok.exe
3. Restart IronGate.

"Npcap required" on client

Install from https://npcap.com/ with "WinPcap API-compatible Mode" enabled.

Client not detecting browser

• Run as administrator
• Check tunnel URL is correct
• Ensure Npcap is installed

"Wrong host" error

Client was generated by different host. Generate new client from your host.

Build takes too long

First PyInstaller build caches dependencies (~60s). Subsequent builds are faster (~30s).

Antivirus blocks exe

PyInstaller exes often trigger false positives. Add to exclusions or sign the exe.

---

Contributing

PRs welcome. Please:

1. Test your changes
2. Update documentation
3. Keep security in mind

---

License

MIT License — do whatever you want, just don't blame me.

---

Credits

Built by [AlexC1991]

Powered by:

• FastAPI
• Ngrok
• Scapy
• PyInstaller

---

⚠️ Disclaimer: This is convenience security for sharing with trusted people. It is not designed for high-security environments or to withstand targeted attacks from skilled adversaries.