shadow-testandClaude Opus 5
48d0c3249a
Round 3 found defects in code written an hour earlier. Both reproduced.
**The handshake poll accepted empty output as a completed handshake.**
`[ "$(… | awk '{print $2}')" != 0 ]` is *true* when `wg show` prints nothing —
which it does when the interface has no peer, and when the interface is gone
(that message goes to stderr). `until` suspends `set -e` and `pipefail`, so
nothing else caught it. The poll added last round to make "success without a
tunnel" impossible produced exactly that. Now requires a number greater than
zero, and waits 20s rather than 10 so a slow link is not rolled back needlessly.
**`down` still sat above the key registration.** Last round moved it below the
token and server-list fetches but not below `addKey`, which is the most
failure-prone of the three — one gateway, by CN, pinned certificate. So a
refused registration still tore down a working tunnel. It now runs after the
last fetch; the key is generated before but written after, since `down` deletes
it. SKILL.md said "after every network fetch has succeeded", which was false;
corrected.
**`up --full` made `host.docker.internal` unresolvable — and `status` said DNS
was fine.** That name is answered only by the resolver being replaced; it is not
in `/etc/hosts`. `gateway.rs` hands it to every container for the LiteLLM
gateway, and Ollama and custom endpoints default to it, so an agent running
`up --full` silently removed the project's model backend. The route was already
excluded; only the name was lost. Now resolved with the old resolver and pinned
into `/etc/hosts` before the swap, restored on teardown, and `status` probes it
— PIA answers public names happily, which is precisely why probing only
`api.anthropic.com` reported "ok". Documented as Trap 4.
**The rollback could abort halfway.** The trap's `{ … }` is not exempt from
`set -e`, and `down`'s `cat`/`tac`/`rm` had no `|| true` — so one failure left
the interface up with all traffic captured, after printing "rolling back".
`down` now runs under `set +e`, the trap tolerates its failure, and the
interface is deleted *first*, since that removes every route pointing at it.
**The account password had a real argv window.** curl does blank `-u`, but only
once running: sampling /proc/<pid>/cmdline caught the plaintext in 2 of 400
tries, between exec and the overwrite. Small, but it is the permanent password
and the token already had the fix. Moved onto the same stdin config — 0 of 400.
Review reported this as a 25-second exposure; that was a wrapper's argv, not
curl's.
entrypoint: the skill install stages into `$_dest.new` and swaps, so a failed
copy leaves the previous copy intact instead of a truncated SKILL.md and no
script, root-owned, on a persisted volume. Verified against a size-limited
filesystem.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
241 lines
11 KiB
Markdown
241 lines
11 KiB
Markdown
---
|
|
name: pia-vpn
|
|
description: Connect this container's traffic through a PIA VPN tunnel over WireGuard, or diagnose one that is not working. Use when asked to enable, route through, check, or tear down a VPN, when traffic needs to leave from a different location, or when DNS or connectivity broke after a VPN was brought up.
|
|
---
|
|
|
|
# PIA VPN
|
|
|
|
Bring this container's traffic out through Private Internet Access over
|
|
WireGuard, using the API PIA documents for headless use.
|
|
|
|
Run `sudo ~/.claude/skills/pia-vpn/pia-wg.sh` with `up`, `up --full`, `down` or
|
|
`status`. Read the rest of this page before the first `up --full` — four of the
|
|
behaviours below are actively misleading if you meet them without warning, and
|
|
each one presents as "the VPN is fine" or "Claude is broken" rather than as
|
|
what it is.
|
|
|
|
## Before anything else: what the toggle does not do
|
|
|
|
Triple-C's **VPN support** setting grants three things — `CAP_NET_ADMIN`, the
|
|
`/dev/net/tun` device, and the `net.ipv4.conf.all.src_valid_mark` sysctl — and
|
|
stops there. It starts no client, builds no tunnel and changes no route.
|
|
|
|
So "the VPN is enabled but traffic isn't going through it" is normally not a
|
|
fault. It means the capability is present and nothing has used it yet. Check
|
|
with `status` before assuming something is broken.
|
|
|
|
If the toggle is off, the script says so and names the setting. It cannot be
|
|
turned on from inside the container; the user changes it in Config → Runtime,
|
|
and it recreates the container on the next start (home and `.claude` volumes
|
|
are preserved — it is not a Reset).
|
|
|
|
## Two modes
|
|
|
|
| | routes | use when |
|
|
|---|---|---|
|
|
| `up` | only `1.1.1.1/32` | verifying the tunnel works without disturbing anything |
|
|
| `up --full` | all public traffic | you actually want traffic leaving via PIA |
|
|
|
|
Prefer `up` first. It proves the handshake, credentials and region are good
|
|
while your own connectivity is untouched, so a failure is cheap.
|
|
|
|
**`up --full` routes Claude Code's own API traffic through PIA.** If the tunnel
|
|
drops, that traffic stops until it recovers or you run `down`. Say so before
|
|
running it — the user may be mid-session, and they will experience the failure
|
|
as Claude going away, not as a VPN problem.
|
|
|
|
## Trap 1: a full tunnel takes DNS with it
|
|
|
|
The container resolves through an address on the Docker network — under Docker
|
|
Desktop, `192.168.65.7` — which sits **outside** the container's own subnet. A
|
|
default route of `0.0.0.0/0`, or the `0.0.0.0/1` + `128.0.0.0/1` pair, captures
|
|
it and posts every lookup into a tunnel that cannot carry private traffic.
|
|
|
|
Nothing resolves after that. The visible symptom is Claude Code reporting it
|
|
cannot connect, because `api.anthropic.com` no longer resolves:
|
|
|
|
```
|
|
$ curl https://api.anthropic.com/v1/messages
|
|
* Could not resolve host: api.anthropic.com (rc=6)
|
|
```
|
|
|
|
`pia-wg.sh` already handles this: it routes `10.0.0.0/8`, `172.16.0.0/12`,
|
|
`192.168.0.0/16` and `169.254.0.0/16` back via the original gateway, then pins
|
|
PIA's own resolvers through the tunnel with `/32` routes that outrank the
|
|
`10/8` exclusion. If you ever route traffic by hand, you owe both halves — the
|
|
exclusions *and* a resolver reachable from wherever you pointed the default.
|
|
|
|
The failure has a quiet twin. Do only the first half — exclude the private
|
|
ranges, leave the resolver alone — and everything *works*, while every DNS
|
|
query travels outside the tunnel to your ISP. A VPN that leaks the full list of
|
|
what you looked up is worse than one that is visibly broken, so `up --full`
|
|
refuses to proceed if PIA does not hand back resolvers rather than carrying on
|
|
without them.
|
|
|
|
The mechanism above is Docker Desktop's. On a user-defined Docker network the
|
|
resolver is `127.0.0.11`, which is loopback and never captured by a default
|
|
route — the trap still exists there (that resolver forwards upstream from
|
|
inside the container's namespace) but arrives by a different path. Check
|
|
`/etc/resolv.conf` rather than assuming which case you are in.
|
|
|
|
## Trap 2: an IP-literal health check cannot see a dead resolver
|
|
|
|
`curl https://1.1.1.1/cdn-cgi/trace` needs no DNS, so it returns a cheerful
|
|
PIA exit address while name resolution is entirely broken. A tunnel verified
|
|
that way looks perfect and works for nothing.
|
|
|
|
`status` resolves a real name for this reason. Trust its `DNS:` line, and if
|
|
you check by hand, resolve a name rather than fetching an address.
|
|
|
|
## Trap 3: in test mode, the obvious probe is the one thing tunnelled
|
|
|
|
`up` routes `1.1.1.1` and nothing else. So checking your address by fetching
|
|
`https://1.1.1.1/cdn-cgi/trace` reports a **PIA** address — not because your
|
|
traffic is going through PIA, but because that single probe is. Everything else
|
|
still leaves directly.
|
|
|
|
This reads exactly like a working full tunnel, and it is the likeliest reason
|
|
someone concludes the VPN is on when it is not. `status` prints both exits in
|
|
test mode for this reason:
|
|
|
|
```
|
|
mode: test route only (1.1.1.1 through the tunnel, nothing else)
|
|
through the tunnel: 64.113.5.73
|
|
everything else: 172.116.197.166 <- your real address
|
|
```
|
|
|
|
Two different addresses there is correct and expected in test mode. If you want
|
|
the second line to change, you want `up --full`.
|
|
|
|
## Trap 4: a full tunnel hides the Docker host unless the name is pinned
|
|
|
|
`host.docker.internal` is answered *only* by the resolver that `up --full`
|
|
replaces — it is not in `/etc/hosts`. Triple-C hands that name to the container
|
|
for the LiteLLM gateway, and host-side Ollama and custom endpoints default to
|
|
it, so losing the name takes the project's model backend down with it.
|
|
|
|
The nasty part is what a naive check reports. PIA's resolvers answer public
|
|
names perfectly well, so a probe of `api.anthropic.com` says everything is fine
|
|
while the Docker host has vanished. `pia-wg.sh` pins the address into
|
|
`/etc/hosts` before swapping the resolver and restores the file on teardown, and
|
|
`status` probes both names — but if you ever rewrite `resolv.conf` by hand, this
|
|
is the one that will not announce itself.
|
|
|
|
## Trap 5: no tunnel survives a restart, and it fails open
|
|
|
|
The network namespace is rebuilt every time the container starts, and nothing
|
|
inside reconnects anything. After a stop/start, Reset or any config change that
|
|
recreates the container, the interface and its routes are gone.
|
|
|
|
State under `/run/pia-wg` rides the snapshot and persists, so leftover files
|
|
make it look as though the tunnel is still configured. It is not. Traffic goes
|
|
out the real address with no error and nothing visibly different.
|
|
|
|
Never infer from `/run/pia-wg` that a tunnel is up. Run `status` — if the
|
|
handshake line is missing, there is no tunnel. Re-run `up` after every start.
|
|
|
|
## Credentials
|
|
|
|
Two lines in `~/pia-creds` — username, then password:
|
|
|
|
```
|
|
p1234567
|
|
your-password
|
|
```
|
|
|
|
Treat the contents as secret: never print the file, never echo the values, and
|
|
never include them in a commit, a log or a message. The script reads it directly
|
|
and does not echo it, and passes PIA's session token to `curl` on stdin rather
|
|
than in the argv, where `ps` would expose it to everything in the container.
|
|
|
|
`PIA_CREDS` points somewhere else — but `sudo` resets the environment, so it
|
|
only takes effect **after** the word `sudo`:
|
|
|
|
```bash
|
|
sudo PIA_CREDS=/path/to/creds ~/.claude/skills/pia-vpn/pia-wg.sh up # works
|
|
PIA_CREDS=/path/to/creds sudo ~/.claude/skills/pia-vpn/pia-wg.sh up # ignored
|
|
```
|
|
|
|
The second form fails silently back to the default path. Same for `PIA_REGION`.
|
|
|
|
## Regions
|
|
|
|
Defaults to `us_chicago`. Override with `PIA_REGION`:
|
|
|
|
```bash
|
|
sudo PIA_REGION=uk_london ~/.claude/skills/pia-vpn/pia-wg.sh up --full
|
|
```
|
|
|
|
List the ids:
|
|
|
|
```bash
|
|
curl -s https://serverlist.piaservers.net/vpninfo/servers/v6 \
|
|
| head -1 | jq -r '.regions[].id'
|
|
```
|
|
|
|
## Verifying
|
|
|
|
`status` prints the handshake, DNS, and which address traffic actually leaves
|
|
from — labelled by mode, so the answer cannot be misread:
|
|
|
|
```
|
|
latest handshake: 2 seconds ago
|
|
transfer: 92 B received, 180 B sent
|
|
DNS: ok (via 10.0.0.243 10.0.0.242)
|
|
mode: full tunnel
|
|
all traffic exits: 64.113.5.244
|
|
```
|
|
|
|
All of it matters. A handshake with `DNS: BROKEN` is trap 1. `mode: test route
|
|
only` with two different addresses is trap 3, and is correct — it means the
|
|
tunnel works and you have not asked for it to carry anything yet. Report the
|
|
mode line when telling someone the VPN is on; "the public IP is a PIA one" is
|
|
true in test mode too, and means much less than it sounds like.
|
|
|
|
## Tearing down
|
|
|
|
`down` restores `resolv.conf` from its backup (only if that backup still looks
|
|
like a resolver file — restoring a truncated one would leave the container with
|
|
no DNS at all), removes exactly the routes that were added, in reverse order,
|
|
and deletes the interface. It is safe to run when nothing is up. Confirm
|
|
afterwards that the public address is back to the container's own.
|
|
|
|
`up` calls it too, but only after the last network fetch — the key registration
|
|
— has succeeded, so a failed `up` leaves an existing tunnel alone rather than
|
|
tearing it down to report a bad password or an unreachable gateway. From that
|
|
point on a rollback is armed: if any step of the setup fails, the tunnel is torn
|
|
down rather than left half-configured.
|
|
|
|
The private key is deleted earlier still — the moment `wg set` has read it,
|
|
while the tunnel is being built. That is not housekeeping: `/run` is in the
|
|
container's writable layer, and recreating or migrating the project runs
|
|
`docker commit` over it *without* tearing the tunnel down first. A key that
|
|
lived for the tunnel's lifetime would be baked into the snapshot image and
|
|
copied forward from then on. The kernel keeps its own copy, so nothing is lost.
|
|
|
|
## What this deliberately does not do
|
|
|
|
- **No killswitch.** `iptables` *is* in the image, so one is buildable — this
|
|
is a deliberate omission, not a missing dependency. Blocking non-tunnel egress
|
|
cuts Claude Code's own API traffic the moment the tunnel drops, which ends the
|
|
session that would otherwise fix it. If the user needs guaranteed egress
|
|
rather than convenient egress, say so plainly and let them decide, rather than
|
|
improvising one.
|
|
- **No autostart.** There is no service manager in the container and Triple-C
|
|
has no start hook, so nothing re-establishes the tunnel on its own. `cron` is
|
|
in the image and `triple-c-scheduler` runs on it, so a scheduled reconnect is
|
|
possible if the user wants one — it is just not set up, and a tunnel that
|
|
reconnects unattended deserves an explicit decision.
|
|
- **Not PIA's desktop client.** `pia-daemon` and `piactl` are installable but
|
|
cannot work headless: the daemon never accepts a client connection without
|
|
the GUI, and `piactl --help` states that connecting requires it. If you find
|
|
one installed, it is not a working alternative to this script.
|
|
- **Not `wg-quick`.** Its `Table=auto` full-tunnel mode routes by firewall mark
|
|
and needs `xt_CONNMARK` from the host kernel, which Docker Desktop for
|
|
Windows (WSL2) does not have and a container cannot load. This script adds
|
|
the routes with `ip route` directly, which works on every host.
|
|
- **IPv4 only.** The `0.0.0.0/1` + `128.0.0.0/1` pair covers v4. A container
|
|
with a global IPv6 address and a v6 default route would leak all v6 traffic
|
|
outside the tunnel; Triple-C's containers do not have one by default, but
|
|
check `ip -6 route show default` before relying on this where it matters.
|