Platform: This version targets Linux first. macOS may work. Windows is not yet supported.

What is it?

localnet-control creates a lightweight TCP proxy that exposes your local dev service to every device on your LAN — no internet required.

Your app (localhost:3000)
        ↓
  localnet proxy  →  http://192.168.1.42:3000
        ↓
  Anyone on your Wi-Fi can open it instantly

Install

pip install localnet-control

Or install from source (for development):

git clone https://github.com/hoysengleang/localnet.git
cd localnet
pip install -e .

Quick Start

# 1. Start your app (e.g. React, FastAPI, etc.)
npm run dev        # running on localhost:3000

# 2. Share it on your network
localnet share 3000

# → Prints: http://192.168.1.42:3000
# → Shows a QR code for mobile devices

Commands

share — Expose a local port

localnet share 3000                        # share port 3000
localnet share localhost:8080              # share a specific host:port
localnet share 3000 --name my-api          # give it a friendly name
localnet share 3000 --port 9000            # listen on a different port
localnet share 3000 --no-qr                # skip the QR code
localnet share 3000 --http-log             # show live HTTP request log (method, path, status, latency)
localnet share 3000 --token myteam123      # require token for access (see Token Auth below)
localnet share 3000 --tunnel               # create a public URL via Cloudflare Tunnel

--tunnel will auto-download cloudflared on first use if it is not already installed.

Access control:

localnet share 3000 --allow 192.168.1.10           # allow only this IP
localnet share 3000 --allow 10.0.0.0/24            # allow a subnet
localnet share 3000 --deny 192.168.1.50            # block a specific IP
localnet share 3000 --allow 192.168.1.0/24 --deny 192.168.1.99   # combine rules

Token auth — How clients provide the token

When you share with --token SECRET, clients must send the token in one of these ways:

1. URL query parameter (browsers, simple clients):

http://192.168.1.42:8100/?token=myteam123

2. Authorization header (API clients, curl, fetch, axios):

curl -H "Authorization: Bearer myteam123" http://192.168.1.42:8100/

Share the full URL with ?token=... for easy access, or tell your team to add the header for API calls.

list — Show active shares

localnet list

stop — Stop a share

localnet stop 3000       # stop by port number
localnet stop my-api     # stop by name

scan — Discover other shares on your network

localnet scan

Finds other localnet-control instances running on your LAN. Great for teams.

info — Show network info

localnet info

Displays your hostname, primary LAN IP, and all network interfaces.

How it works

1. Detects your LAN IP automatically using a UDP socket trick (no traffic sent)
2. Binds to 0.0.0.0 on the chosen port so all network interfaces are reachable
3. Proxies TCP traffic bidirectionally between LAN clients and your local service
4. Prints a shareable URL and QR code so anyone can connect instantly
5. Saves state to ~/.localnet-control/services.json to track active shares
6. Broadcasts presence via UDP so localnet scan can discover other instances

Options Reference

Requirements

Publish to PyPI (for maintainers)

1. Create a PyPI account: https://pypi.org/account/register/
2. Set up Trusted Publishing: PyPI → Account Settings → Publishing → Add pending publisher:
   • PyPI project: localnet-control
   • Owner: hoysengleang, Repo: localnet
   • Workflow: release.yml
3. Bump version in pyproject.toml and src/localnet_access/__init__.py
4. Push a tag:

   git tag v0.2.0
   git push origin v0.2.0
   

5. The GitHub Action will build and publish to PyPI.

Project Structure

src/localnet_access/
├── cli.py        # Commands and argument parsing
├── proxy.py      # Async TCP proxy engine
├── network.py    # LAN IP detection and port utilities
├── display.py    # Terminal UI with rich
├── acl.py        # IP/CIDR access control rules
├── scanner.py    # LAN discovery (broadcast + scan)
└── Policy/       # Policy enums (discovery port, magic, etc.)