Lan Direct

lan-direct

A skill and a browser MCP for coding agents behind a full-tunnel VPN — Claude Code and Codex.

Your VPN has to stay on, because that's how the agent reaches its API. But the app you're testing calls services that reject the VPN's foreign exit IP: a domestic API, a payment or SMS gateway, a bank endpoint. Turning the VPN off isn't an option — it cuts the agent off.

lan-direct gives the app an ISP-direct path while the agent stays on the tunnel. No admin, no routing-table edits, no VPN reconfiguration. How it works.

Install

Requires Node ≥ 20.6, plus PowerShell on Windows or bash and curl on Linux/macOS. No admin, no symlinks, no renaming.

From npm

npm install -g lan-direct

lan-direct install-skill # or --codex claude mcp add playwright-split --scope user "--" npx -y lan-direct browser

Then restart the agent. That's it — the same three lines on every platform.

npx -y lan-direct browser is the better MCP command however you install: it survives the checkout moving, which an absolute path into a clone does not.

Why `"--"` is quoted. On Windows claude resolves to claude.ps1, and PowerShell's

parameter binder strips a bare -- before the script ever sees it. The CLI then reads -y

as one of its own flags and fails with error: unknown option '-y'. Quoting protects it,

and quotes are a no-op in bash — so the same line works in PowerShell, bash and cmd.

From a clone

Prefer this if you want to edit the skill or track it — one git pull updates everything, where npm needs npm update -g lan-direct && lan-direct install-skill because install-skill copies files rather than linking them.

Either way, your own host list at ~/.lan-direct-hosts is never touched.

1. Clone into your agent's skills directory. Both agents discover skills by scanning a directory for SKILL.md — they just scan different ones.

# Windows - Claude Code

git clone https://github.com/farshadmomo/lan-direct.git "$HOME\.claude\skills\lan-direct"

Windows - Codex

New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills" | Out-Null git clone https://github.com/farshadmomo/lan-direct.git "$HOME\.agents\skills\lan-direct"

# Linux / macOS - Claude Code

git clone https://github.com/farshadmomo/lan-direct.git ~/.claude/skills/lan-direct

Linux / macOS - Codex

mkdir -p ~/.agents/skills git clone https://github.com/farshadmomo/lan-direct.git ~/.agents/skills/lan-direct

2. Register the browser MCP:

powershell -NoProfile -ExecutionPolicy Bypass `

-File "$HOME\.claude\skills\lan-direct\scripts\install.ps1"

The installer verifies the bypass actually works, registers the server against this checkout, and prints the equivalent ~/.codex/config.toml block for Codex. Safe to re-run — it replaces the existing entry rather than duplicating it.

On Linux/macOS there's no installer script; register it directly:

claude mcp add playwright-split --scope user "--" \

node ~/.claude/skills/lan-direct/scripts/lan-browser.mjs --port 8900

Restart the agent. Then /lan-direct in Claude Code, or in either agent just describe the problem — the description frontmatter is the trigger, firing on phrasings like "test this while my VPN is on" or "the API rejects the VPN IP".

To update: git -C pull. No reinstall needed.

Using both agents from a single clone

Clone once, then link the second location. On Windows a junction works without admin or Developer Mode, unlike a symlink:

git clone https://github.com/farshadmomo/lan-direct.git "$HOME\.claude\skills\lan-direct"

New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills" | Out-Null cmd /c mklink /J "$env:USERPROFILE\.agents\skills\lan-direct" "$env:USERPROFILE\.claude\skills\lan-direct"

macOS/Linux:

git clone https://github.com/farshadmomo/lan-direct.git ~/.claude/skills/lan-direct

mkdir -p ~/.agents/skills ln -s ~/.claude/skills/lan-direct ~/.agents/skills/lan-direct

One git pull then updates both.

Installing somewhere else (for editing the skill)

Clone wherever you like and link it in. A junction needs no admin; a symlink needs an elevated shell or Developer Mode:

git clone https://github.com/farshadmomo/lan-direct.git "D:\projects\lan-direct"

cmd /c mklink /J "$env:USERPROFILE\.claude\skills\lan-direct" "D:\projects\lan-direct"

However you install it, the directory inside the skills folder must be named lan-direct — both agents discover by directory name, and it has to match name: in SKILL.md.

Which hosts go via the ISP

Rules live in lan-hosts.txt and are suffix matches:

.ir             every .ir host

digikala.com also seller.digikala.com, api.digikala.com, ...

Anything not matched takes the tunnel. List domestic hosts only — adding a foreign one sends it out through an ISP that may filter it.

The shipped list covers .ir wholesale plus the Iranian services that live on other TLDs: payment (zarinpal, payping, nextpay), SMS/OTP (kavenegar, melipayamak, farazsms, ippanel), hosting (parspack, hostiran, mizbanfa), maps (neshan), commerce (digikala, torob, basalam), education and jobs (quera, faradars, maktabkhooneh, 7learn, irantalent), AI (hoosha, gapgpt), and the analytics domains those sites embed (najva, yektanet). Every one was checked: all are unreachable over the tunnel and respond over the ISP.

Adding your own

Put them in `~/.lan-direct-hosts`, one per line, same format:

# my own

aparat.com internal.corp

That file is never touched by git pull, and is read each time the browser starts — no reinstall, no restart of anything but the browser. Rules from all three sources merge: shipped file, your file, and any --lan-hosts a,b passed at launch.

Getting a rule wrong fails in a way that looks like the site being down, so the proxy prints the route it chose for every connection. Check that before blaming the site — or ask directly, without starting anything:

$ lan-direct route hoosha.com youtube.com api.anthropic.com

24 rules in effect

hoosha.com lan ISP (bound) youtube.com vpn tunnel api.anthropic.com vpn tunnel

What's in the box

Two halves, installed together:

The MCP is what makes browsing work at all — Chromium has no source-binding flag, so a browser can only reach the ISP through a proxy. Without it the skill covers backends and CLIs but not pages.

How it works

Per-socket source-address binding. A socket explicitly bound to the physical adapter's IP takes that adapter's default route instead of the tunnel's:

$ curl -s https://api.ipify.org                            # 203.0.113.7    (VPN exit)

$ curl -s --interface 192.168.1.20 https://api.ipify.org # 198.51.100.42 (real ISP)

No admin rights, no routing-table edits, no VPN reconfiguration, nothing global. Because it's per-socket it is opt-in by construction — a process that doesn't ask for it *cannot* be affected. That's the property that keeps the agent on the tunnel.

This is deliberately not route add. A static route is global: it would pull every process off the tunnel for that destination, the agent included, and it needs admin.

A server process has no --interface flag, so there are two ways to give it one:

The Node trap

If your backend is Node, `HTTP_PROXY` will not work and will fail silently.

Native fetch runs on Node's built-in undici, which ignores proxy environment variables on Node ≤ 23 and accepts no https.Agent. Verified on Node 22.20: plain env vars, NODE_USE_ENV_PROXY=1, and --use-env-proxy all do nothing — the proxy log stays empty while traffic goes out over the VPN. This hits Next.js, the openai SDK, and anything else on native fetch.

lan-bind.mjs patches net/tls in a preload, which reaches the bundled undici. That covers native fetch, the openai SDK, axios, node-fetch, got and plain http/https at once — no dependency, no proxy process, no HTTP_PROXY. NODE_OPTIONS propagates to forked workers, so it covers Next.js and Vite dev servers.

It skips loopback destinations on purpose: a socket sourced from the LAN IP cannot reach 127.0.0.1, so without that guard any app with a local Redis/Postgres/Mongo would die on EADDRNOTAVAIL.

Manual use

All paths below use $skill for wherever you installed it:

$skill = "$HOME\.claude\skills\lan-direct"    # Claude Code

$skill = "$HOME\.agents\skills\lan-direct" # Codex

1. Detect and verify. Exits 0 only if the bypass actually works.

powershell -NoProfile -ExecutionPolicy Bypass -File "$skill\scripts\lan-detect.ps1"

bash ~/.claude/skills/lan-direct/scripts/lan-detect.sh    # Linux / macOS

Emits lanIp, gateway, lanDns, subnet, tunnelActive, vpnAdapter, directEgress, lanEgress, fakeIpDns, bypassWorks. It probes twice and compares, rather than assuming — and refuses to proceed if the bypass doesn't hold, so you never get a false pass.

2a. Node backend. Copy-paste as-is; only lanIp needs filling in:

$env:LAN_BIND     = "<lanIp>"

$env:NODE_OPTIONS = "--import file:///$($skill -replace '\\','/')/scripts/lan-bind.mjs" npm run dev

Same thing from Git Bash, with the path written out:

LAN_BIND=<lanIp> \

NODE_OPTIONS="--import file:///C:/Users/YOU/.claude/skills/lan-direct/scripts/lan-bind.mjs" \ npm run dev

--import needs an absolute file:// URL with forward slashes on Windows — a bare Windows path fails.

2b. Anything else. Start the proxy:

node "$skill\scripts\lan-proxy.mjs" --bind <lanIp> --self-test    # run with the tunnel UP

node "$skill\scripts\lan-proxy.mjs" --bind --port 8899

Then launch the backend with HTTP_PROXY=http://127.0.0.1:8899, HTTPS_PROXY=http://127.0.0.1:8899, NO_PROXY=localhost,127.0.0.1, .

See SKILL.md for stacks where HTTP_PROXY still isn't enough — notably PHP under Apache, where the service doesn't inherit your shell and libcurl never sees the variables.

Browsing both worlds at once

Neither path is a superset of the other. Measured on an Iranian ISP behind a foreign tunnel:

That last row is why the agent must never be moved off the tunnel — do it and the agent stops working entirely.

The browser MCP handles the mix in one session. Chrome is told to send *everything* to the proxy and makes no routing decision itself; the proxy reads th