# lan-direct

[![check](https://github.com/farshadmomo/lan-direct/actions/workflows/check.yml/badge.svg)](https://github.com/farshadmomo/lan-direct/actions/workflows/check.yml)
[![npm](https://img.shields.io/npm/v/lan-direct)](https://www.npmjs.com/package/lan-direct)
[![license](https://img.shields.io/npm/l/lan-direct)](LICENSE)

**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](#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

```bash
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.

```powershell
# 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"
```

```bash
# 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
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:

```bash
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 <that directory> pull`. No reinstall needed.

<details>
<summary>Using both agents from a single clone</summary>

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

```powershell
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:

```bash
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.

</details>

<details>
<summary>Installing somewhere else (for editing the skill)</summary>

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

```powershell
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`.

</details>

## Which hosts go via the ISP

Rules live in [`lan-hosts.txt`](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:

```console
$ 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:

| | What it does |
|---|---|
| **The skill** (`SKILL.md`) | Teaches the agent the whole workflow — detect, verify, pick a mechanism per stack, tear down. Discovered automatically by scanning for `SKILL.md`. |
| **The browser MCP** (`lan-browser.mjs`) | A Playwright MCP server that starts and owns its own proxy, and routes **per host**: domestic sites via the ISP, everything else via the tunnel, in one browser session. |

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:

| Your backend | Mechanism |
|---|---|
| **Node / Next.js** | `lan-bind.mjs` — a `--import` preload that binds every socket in the process |
| Everything else | `lan-proxy.mjs` — a local proxy whose *outbound* sockets are bound, driven by `HTTP_PROXY` |

## 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:

```powershell
$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
powershell -NoProfile -ExecutionPolicy Bypass -File "$skill\scripts\lan-detect.ps1"
```

```bash
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:

```powershell
$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:

```bash
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:

```powershell
node "$skill\scripts\lan-proxy.mjs" --bind <lanIp> --self-test    # run with the tunnel UP
node "$skill\scripts\lan-proxy.mjs" --bind <lanIp> --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,<subnet>`.

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:

| | via VPN | via ISP |
|---|---|---|
| youtube, x, facebook, telegram, reddit | work | dead |
| hoosha, neshan, avalai | dead | work |
| github, google, npm | work | work |
| **api.anthropic.com** | **works** | **403** |

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 the hostname out of each `CONNECT`
(visible in plaintext, before TLS) and decides:

```js
useBind(host) ? net.connect({ host, port, localAddress })   // ISP
              : net.connect({ host, port })                  // tunnel
```

There is no "use the VPN" code path. Binding is the only action taken — skip it and the OS
routing table applies, which the tunnel owns. LAN is opt-in; the tunnel is what happens
otherwise.

It is per connection, not per session. Two `fetch` calls from the *same page* can take
different physical routes — measured, on one page in one tab:

| Request | Egress |
|---|---|
| `api.hoosha.com` (listed) | ISP |
| `api.ipify.org` (not listed) | VPN |

Every proxy log line names the route it chose:

```
CONNECT  lan  hoosha.com:443
CONNECT  vpn  youtube.com:443
```

The browser's proxy runs on **8900**, deliberately not the **8899** used for backend testing
above. The MCP reuses whatever is already listening on its port, so sharing the number would
let a bind-everything backend proxy silently capture the browser and push all of its traffic
through the ISP — breaking exactly the sites the tunnel exists for.

## Contents

| File | Purpose |
|---|---|
| `SKILL.md` | The skill: workflow, per-stack recipes, troubleshooting |
| `lan-hosts.txt` | Hosts routed via the ISP. Yours go in `~/.lan-direct-hosts` |
| `scripts/install.ps1` | Registers the browser MCP against this checkout. Safe to re-run |
| `scripts/lan-detect.ps1` | Finds the physical adapter and **proves** the bypass works. JSON out |
| `scripts/lan-detect.sh` | The same, for Linux and macOS — same JSON, same exit-code contract |
| `scripts/lan-bind.mjs` | Node preload — binds the whole process. The answer for Node/Next.js |
| `scripts/lan-proxy.mjs` | Dependency-free HTTP/CONNECT proxy, with optional per-host routing |
| `scripts/lan-browser.mjs` | The MCP server — Playwright plus a proxy it starts and owns |
| `scripts/lan-route.mjs` | The routing rules, importable and tested. Also the library export |
| `bin/lan-direct.mjs` | The CLI: `detect`, `proxy`, `browser`, `route`, `install-skill` |
| `test/` | `npm test` — routing, rule parsing, the proxy, and the preload |

Requires Node ≥ 20.6 and `curl` (built into Windows 10+, standard elsewhere). No dependencies.

## Development

```bash
npm test          # node:test, no install step - there are no dependencies
```

34 tests. The routing predicate gets the most attention because it's the only logic here
whose failure is silent — a wrong match sends traffic out the wrong physical network with no
error and no log line. Both mutations it exists to catch are verified to fail the suite: a
naive `endsWith` (so `evilhoosha.com` matches `hoosha.com`) and a missing loopback guard.

The preload is tested in a real child process with `LAN_BIND` set to `192.0.2.1` — an address
the machine can't own, so a bound socket fails instantly. That's what proves the patch is
active rather than quietly doing nothing.

What CI can't cover: `lan-proxy.mjs --self-test`, which needs a live tunnel and a physical
adapter. Run it by hand with the VPN up. Changes are listed in [CHANGELOG.md](CHANGELOG.md).

One gotcha if you're on an old runtime: **Node 20.6.0 can't run the suite** — every assertion
passes and then the test runner never exits. That's a bug in that release's runner, not in
lan-direct, which runs fine on it. Any current 20.x or 22 is fine.

## Notes

- The proxy listens on `127.0.0.1` only. Binding wider would publish an open proxy to the LAN.
- `lan-direct route <host>` shows which network a host would leave by, using your merged rule
  list. Faster than starting the browser to find out.
- The `.ps1` files are deliberately pure ASCII: Windows PowerShell 5.1 reads BOM-less UTF-8 as
  ANSI, and a stray em dash breaks the parser. CI enforces this.
- Under fake-IP DNS (sing-box, clash), pass `--dns <lanDns>`. `dns.setServers()` doesn't affect
  `dns.lookup()`, which goes through the OS resolver the tunnel owns.
- `pkill -f lan-proxy` from Git Bash does not kill a Windows `node.exe`. Use the PowerShell
  teardown in `SKILL.md`.

## Verified against

nekoray / sing-box TUN on Windows 11, Node 22.20, Intel Wi-Fi — tested end to end on a real
Next.js 16 app calling Neshan (Iranian maps) and AvalAI (LLM gateway), both of which reject
foreign IPs outright:

| | via VPN | via ISP |
|---|---|---|
| AvalAI `/models`, `/chat/completions` | `ECONNRESET` | 200, real completion + token usage |
| Neshan reverse geocode | no response | 200, correct address |
| Neshan routing / geocoding | no response | 200 |
| Next.js `/api/reverse`, `/api/chat` | — | 200, live data through the full stack |

The browser MCP was tested the same way: a domestic AI platform and YouTube opened
back to back in one session, the domestic site's own CDN reporting the ISP address and
country `IR` while YouTube rendered its German-locale shell over the tunnel.

The agent's own connection stayed on the tunnel throughout.

Adapter discovery is generic — `Get-NetAdapter -Physical` on Windows, a sysfs `device` symlink
on Linux, `networksetup` on macOS — so WireGuard, OpenVPN, WARP and similar should work. But
`lan-detect` verifies empirically rather than assuming, and exits non-zero when it can't.

**Platform status.** Windows is the tested path, end to end. `lan-detect.sh` has been run on
Linux (Ubuntu 24.04) and returns the correct interface, gateway, DNS, routes and exit codes —
but on a machine with no tunnel of its own, so the *bypass-verified* branch is unproven there.
macOS is written from the documented behaviour of `networksetup`/`ipconfig`/`netstat` and has
not been run at all. Both refuse rather than guess, so the failure mode is a clear error, not
silent VPN traffic. Reports welcome.

One caveat specific to Linux: a bound source address does not by itself override the routing
table the way it does on Windows, so a tunnel using policy routing may keep the traffic even
when bound. That is exactly what the two probes detect — if it happens, `lan-detect.sh` says so
and names the fix instead of reporting success.

Also unproven: `lan-detect`'s "kill-switch detected" branch, which needs the VPN in a state the
test machine couldn't produce.

## License

MIT — see [LICENSE](LICENSE).