devlinker 1.4.6

A lightweight proxy that combines your frontend and backend into one link for easy development and sharing.

Dev Linker

Dev Linker starts your local development stack and routes frontend and backend traffic through one proxy URL, with optional LAN and public sharing.

⚡ Quick Start (2 Minutes)

Install:

pip install devlinker

Run your apps:

# Backend (example)
uvicorn main:app --reload

# Frontend (example)
npm run dev

Run DevLinker:

devlinker

Open:

http://localhost:8001

Done ✅

🧠 How DevLinker Works

Request flow:

Browser -> DevLinker Proxy -> Frontend or Backend

Routing rules:

• / routes to frontend (React/Vite)
• /api/* routes to backend (FastAPI/Flask/Node)

DevLinker acts as a smart proxy and optional tunnel layer for local, LAN, and public development links.

Architecture diagram:

flowchart LR
     B[Browser / Mobile] --> P[DevLinker Proxy]
     P --> F[Frontend Dev Server\nVite/React]
     P --> A[Backend API\nFastAPI/Flask/Node]
     P --> T[Optional Tunnel\nCloudflare/ngrok]

🎯 Use Cases

• Test APIs and UI flows on mobile devices over WLAN
• Share local work instantly with teammates using one public URL
• Debug frontend-backend integration from a single entrypoint
• Reduce CORS/preflight issues during development

🖼️ Demo & Screenshots

• Terminal startup output: add screenshot at docs/images/terminal-startup.png
• Browser app via proxy: add screenshot at docs/images/browser-proxy.png
• Public URL share demo: add screenshot at docs/images/public-url.png

Features

• 🚀 Unified Dev Proxy: Combines frontend (Vite/React) and backend (FastAPI/Flask/Node/Docker) into a single local and public URL.
• 🔍 Auto Detection: Detects frontend/backend ports, runtime, Docker containers, and Vite servers automatically.
• 📡 Debug Request Logger: Live API traffic lines (method, path, status, latency) only in debug mode.
• 🧩 Backend-Only Mode: If no frontend is detected, DevLinker still runs and forwards all traffic to backend.
• 🔁 Runtime API URL Injection: Injects runtime browser patching so hardcoded localhost API calls are rewritten to the active proxy/tunnel origin.
• 🛡️ Proxy CORS + Preflight: Handles common CORS/preflight behavior at the proxy layer, including credential-safe Origin handling.
• 🧠 Smart Detection & Doctor: Real-time request analysis, backend intelligence, log analyzer, and devlinker doctor for instant diagnostics.
• 🛡️ Auto-Fix Engine: devlinker fix applies safe fixes (like VITE_API_URL) and suggests code changes.
• 🌍 Public Sharing: Share your local dev environment instantly with the --url flag at startup.
• 📡 WLAN Sharing: Prints LAN URL for same-network device access.
• 🔒 Secure Token Linking: Optional token gate for LAN/public access with DEVLINKER_LINK_TOKEN.
• 📊 Browser API Logs Dashboard: Open /__devlinker/dashboard for lightweight live API visibility.
• 🧑‍💻 Interactive CLI: Modern, colorized, emoji-rich terminal UX for all commands.
• 🧩 Zero Config: Works out-of-the-box for most FastAPI, Flask, Vite, and Docker projects.
• 🧪 Runtime Smoke Test: Built-in test for end-to-end proxy validation.
• 🛠️ Extensible: Modular architecture for future SaaS, dashboard, and team features.

Support DevLinker

If DevLinker helps you ship faster, consider supporting the project:

💖 Support DevLinker

• 💖 UPI: devlinker@upi
• 🔗 UPI link: upi://pay?pa=devlinker@upi&pn=DevLinker&cu=INR&tn=Support%20DevLinker%20Project%20🚀

CLI Commands & Options

• devlinker — Start proxy (local only, fast)
• devlinker support — Show UPI support QR code in terminal
• devlinker --url — Start with public tunnel (Cloudflare/ngrok)
• devlinker doctor — Diagnose issues, see categorized problems and fixes
• devlinker fix — Auto-fix common issues (env, API paths, config)
• devlinker --frontend 5173 --backend 5000 — Override detected ports
• devlinker --docker — Auto-start Docker backend
• devlinker --no-tunnel — Explicitly force local/WLAN-only mode (no public tunnel)
• devlinker --no-lan — Hide WLAN sharing URL
• devlinker --interactive-backend — Prompt to choose backend if multiple found
• devlinker --proxy-port 18000 — Use custom proxy port
• devlinker --debug — Enable debug mode (turns on live API request logger)
• devlinker --version — Show version

Security token (optional):

set DEVLINKER_LINK_TOKEN=your-secret-token
devlinker --url

When enabled, LAN/public requests must include one of:

• query param dl_token=...
• header X-DevLinker-Token: ...
• header Authorization: Bearer ...

Built-in API logs dashboard:

http://localhost:<proxy-port>/__devlinker/dashboard

JSON stream endpoint used by the dashboard:

http://localhost:<proxy-port>/__devlinker/logs

Project Structure

devlinker/
├── devlinker/
│   ├── __init__.py
│   ├── main.py
│   ├── runner.py
│   ├── detector.py
│   ├── proxy.py
│   └── tunnel.py
├── setup.py
├── README.md
└── requirements.txt

Install

For local development:

pip install .

For editable local development:

pip install -e .

After publishing to PyPI:

pip install devlinker

Run

devlinker

Direct module run (without installing entrypoint script):

python -m devlinker.main

Typical startup output (TTY with Rich available):

╭─────────────────────────────╮
│ ♾️  DevLinker v1.4.5        │
│ Smart Local Dev Environment │
╰─────────────────────────────╯

✔ Detecting project...
⏳ Booting local services...

╭───────── DevLinker Ready ─────────╮
│ Proxy     http://localhost:8001   │
│ WLAN      http://192.168.1.3:8001 │
│ Public    disabled (use --url)    │
╰───────────────────────────────────╯

✨ Ready in 5.5s
Powered by DevLinker 🚀

Enable debug mode with live API request logging:

devlinker --debug

Debug mode request logger sample:

🛠 Debug mode enabled: live API request logger is ON

📡 Requests (Live)
GET    /api/users               200  45ms
POST   /api/login               401  120ms

Version check:

devlinker --version

Optional overrides:

devlinker --frontend 5173 --backend 5000

Backend override alias:

devlinker --backend-port 3001

Enable Docker auto-start explicitly:

devlinker --docker

Tunnel and Sharing Modes

By default, DevLinker starts fast local proxy only (no tunnel). It prints a LAN URL when it can detect a local network interface, and you can share that link with devices on the same Wi-Fi/LAN.

LAN-only quick start:

devlinker

You can also pass --no-tunnel to explicitly enforce no public tunnel startup:

devlinker --no-tunnel

--no-tunnel does not disable frontend/backend linking. DevLinker still starts the local proxy and routes frontend + backend through the same local entry URL.

For access from another network, start with a public tunnel using the --url flag:

devlinker --url

This starts the proxy and opens a public tunnel (Cloudflare or ngrok). The output will show:

🌍 Enabling public tunnel...
✔ Tunnel provider: Cloudflare
✔ Public URL:
     https://xxxx.trycloudflare.com
ℹ Tip: Ctrl+Click to open link
ℹ Share this link with collaborators.

If your friend is on the same Wi-Fi/LAN, use the printed LAN URL like http://192.168.x.x:<proxy-port>. If they are outside your network, use the public tunnel URL instead.

To force tunnel off (even if --url is passed):

devlinker --no-tunnel

When running without --url, you’ll see local/WLAN output with public disabled:

Proxy:    http://localhost:8000
WLAN:     http://192.168.1.5:8000
Public:   disabled (use --url)

WLAN usage notes:

• localhost works only on the machine running DevLinker.
• Use the printed WLAN URL on phones/laptops connected to the same Wi-Fi/LAN.

WLAN troubleshooting checklist:

1. Ensure both devices are on the same Wi-Fi/subnet.
2. Allow Python/DevLinker through firewall prompts (Private networks).
3. Keep Universal Mode enabled (default) so localhost API calls are rewritten safely for LAN/public links.

Disable WLAN URL output:

devlinker --no-lan

Smart Detection & Auto-Fix System

DevLinker now includes an AI-powered detection and auto-fix engine:

• Request Inspector: Real-time analysis of proxy traffic for common mistakes (missing /api prefix, 404s, CORS risks, upstream failures)
• Backend Intelligence: Probes backend endpoints and type at startup for smarter routing and hints
• Log Analyzer: Converts error messages (CORS, 404, connection refused) into human-readable explanations and actionable fixes
• Smart Warning Engine: Prints clean CLI warnings and suggestions, e.g.:

⚠️  Detected direct backend call (localhost:5000)
👉 Use /api/* instead of direct URL

All detection and fixes are modular, async-compatible, and production-ready. See devlinker/proxy.py, devlinker/detector_ai.py, and devlinker/logger.py for implementation.

Interactive backend selection (when local and Docker are both detected):

devlinker --interactive-backend

Disable interactive backend selection (keeps local-first behavior):

devlinker --no-interactive-backend

If port 8000 is already in use:

devlinker --frontend 5173 --backend 5000 --proxy-port 18000

Default behavior also tries fallback ports automatically when 8000 is busy:

⚠ Port 8000 in use
ℹ Using proxy port: 8001

By default it scans the next 10 ports after the requested one, then tries 18000.

Frontend detection behavior:

• Scans Vite defaults and fallback ports (5173 through 5190)
• Also checks common alternatives (3000, 4173, 8080)
• Retries during startup to catch slow boot cases
• Performs readiness gating before proxy startup (waits until frontend looks like Vite and backend responds)

Important Frontend Rule

Frontend requests must use relative API paths:

fetch("/api/endpoint")

Do not hardcode backend host URLs in frontend code.

DevLinker injects runtime config and request patching in proxied HTML so frontend API calls are routed through the active proxy/tunnel origin without requiring source edits or frontend rebuilds.

Use the proxy URL as your single entry point during development:

http://localhost:<proxy-port>

Avoid direct backend calls like http://localhost:5000 from browser-facing code.

Configuration File

DevLinker loads config from the first file found in this order:

1. devlinker.yaml
2. devlinker.yml
3. devlinker.json

Example:

frontend: 5173
backend: 5000
proxy_port: 8001
backend_entry: main.py
api_prefix: /api
strip_prefix: true

Config key notes:

• backend_entry: Optional Python backend startup file override (for example main.py)
• api_prefix: Prefix DevLinker treats as API traffic (default: /api)
• strip_prefix: When true, strips configured api_prefix before forwarding to backend
• Public tunnel is opt-in at runtime using --url; local/WLAN mode works without ngrok/cloudflared.

Backend Auto-Detection

Backend port detection runs in this order:

1. Check localhost port 5000
2. If not found, query Docker via Docker SDK (docker.from_env()) for published host-to-container port mappings
3. Prioritize containers using labels when present (devlinker.role=backend, optional devlinker.port=<container-port>)
4. Otherwise rank containers by likely backend identity (name hints like backend/api plus project-name hints)
5. Use the best mapped host port automatically, even when internal port is not 5000
6. If nothing is found, print next-step guidance and exit

Python backend entry detection supports automatic discovery of:

• app.py
• main.py
• server.py
• run.py
• manage.py

If backend_entry is set in config, DevLinker uses it first and falls back to the discovery list.

If Docker SDK is unavailable, Dev Linker falls back to Docker CLI parsing as a compatibility path.

When both Local and Docker backends are available, Dev Linker prompts you to choose one (TTY mode) unless --no-interactive-backend is used.

If backend detection fails, Dev Linker prints a clear checklist showing what it checked and how to recover.

Detection messages include source labels, for example:

[OK] Backend detected (Local) -> port 5000

Example Docker dynamic-port message:

[WARN] Backend not found on port 5000
[INFO] Checking Docker containers...
[OK] Backend detected (Docker) -> port 32768

Dev Linker checks backend runtime in this order:

1. Docker Compose (backend/docker-compose.yml, docker-compose.yaml, compose.yml, or compose.yaml)
2. Docker (backend/Dockerfile)
3. Node (backend/package.json)
4. Python (backend/requirements.txt or discovered entry file such as app.py / main.py)

Backend startup commands:

• Docker Compose (default): manual run docker compose up --build in backend/
• Dockerfile (default): manual run docker build -t devlinker-backend . then docker run --rm -p 5000:5000 devlinker-backend
• Docker Compose/Dockerfile with --docker: Dev Linker runs those Docker commands for you
• Node: npm run dev (or npm start when dev is missing)
• Python: python <discovered-entry> (auto: app.py, main.py, server.py, run.py, manage.py, or configured backend_entry)

For containerized Flask backends, ensure:

• App binds to all interfaces: app.run(host="0.0.0.0", port=5000)
• Port mapping is present: -p 5000:5000

Notes

• runner.py expects frontend project in frontend/ and backend project in backend/, with automatic Python entry discovery.
• If those paths do not exist, Dev Linker skips launch and only tries to detect already-running services.
• If frontend is missing but backend is available, DevLinker continues in backend-only mode.
• Tunnel selection order is: cloudflared (TryCloudflare), then ngrok.
• If cloudflared is unavailable and ngrok is not configured, Dev Linker prints one-time setup guidance.
• You may need to set ngrok auth once on your machine using ngrok config add-authtoken .
• Dev Linker prints a public URL with ngrok-skip-browser-warning=true only when ngrok is used.
• Startup output includes selected tunnel provider (cloudflare or ngrok).
• Proxy layer now supports WebSocket upgrades, including Vite HMR over shared links.
• Proxy handles common CORS/preflight behavior and adds camera/mic permissions policy headers.
• Live API request logging is disabled by default and only enabled with devlinker --debug.
• Proxy listens on 0.0.0.0 and can print a WLAN URL for same-network sharing.
• If WLAN access fails on Windows, allow the proxy port in firewall and confirm devices are on the same network.

Runtime Smoke Test

Run this test to validate proxy behavior end-to-end (frontend HTTP route, backend API forwarding, and WebSocket pass-through):

python -m unittest tests.test_proxy_runtime

The test spins up lightweight local frontend and backend apps, starts Dev Linker proxy, and verifies:

• GET / is routed to frontend
• POST /api/login is routed to backend
• ws://.../hmr round-trip works through proxy

Troubleshooting Links

If local or shared links show blank pages, connection refused errors, or 404s, check these common causes:

1. Docker backend binding

• Symptom: http://localhost:<backend-port> refuses connection.
• Cause: backend process inside container is bound to 127.0.0.1 instead of 0.0.0.0.
• Fix: run backend with host 0.0.0.0 (example FastAPI/Uvicorn: uvicorn app.main:app --host 0.0.0.0 --port 8000).

2. API prefix mismatch

• Symptom: frontend loads through Dev Linker but API calls return 404.
• Cause: frontend calls /api/..., but backend routes are mounted without /api prefix.
• Fix: expose backend routes under /api (or adjust frontend paths to match backend routes).

3. Vite host restrictions

• Symptom: direct Vite URL works, Dev Linker proxy URL is blank or blocked.
• Cause: Vite host protections reject proxied host/port.
• Fix: set Vite server.host and server.allowedHosts to allow proxy use.

Quick isolate sequence:

1. Open http://localhost:<backend-port>/docs (or /health) directly.
2. Open Dev Linker local proxy URL and verify UI loads.
3. Use browser network tab to check API status codes for /api/* requests.

Real-Time Development

• Run devlinker to share one combined frontend/backend URL.
• Vite HMR and other WebSocket flows are proxied end-to-end through Dev Linker.
• Keep using relative frontend API paths (for example, /api/endpoint) so routing stays consistent locally and over tunnel.