Stop a failed up from tearing down a working tunnel

The previous commit moved `down` to the top of `up` to fix a resolv.conf
idempotency bug, and in doing so put it *before* every network fetch that can
fail. Re-review caught it and I reproduced it: with a tunnel up, an `up` that
fails on bad credentials left `pia0` gone and traffic silently back on the real
address, while the error talked only about credentials. A privacy regression
introduced by a correctness fix.

`down` now runs after the token, server list and key registration have all
succeeded — nothing above that line touches the network stack — and still
clears the stale backup it was added for.

Everything after it is covered by a rollback. Note this is an EXIT trap with a
flag, not `trap ... ERR`: my first attempt used ERR and did not fire at all,
because ERR is not inherited by shell functions without `set -E`, so a failure
inside add_route missed it, and `die` exits explicitly, which is not an error.
Verified by forcing a route collision — the tunnel is torn down and DNS is
intact, where before the fix it was left half-configured with DNS dead.

Also from the review:

- **The private key lived on disk for the whole life of the tunnel.**
  `commit_container_snapshot` blanks env vars, never files, and nothing tears
  the tunnel down before a recreate or migrate — so the `down`-time cleanup
  never covered the path that put a key in a snapshot in the first place. It is
  now deleted the moment `wg set` has read it; the kernel keeps its own copy,
  verified by checking the interface still works afterwards.
- **`up` claimed success without a handshake.** An unreachable peer still
  routes — into a black hole — so `up --full` could exit 0 having pointed all
  traffic and resolv.conf at a peer that never answered, with `status` printing
  "mode: full tunnel". Now polls for a handshake and rolls back if none arrives.
- **`status` needed root and did not check.** `wg show` fails unprivileged and
  was swallowed, so an unprivileged run printed "no tunnel up" and then "mode:
  full tunnel" in the same breath. An agent reading the first line would re-run
  `up` — which, before the fix above, destroyed the tunnel it failed to see.
- **The killswitch bullet was false.** It said `iptables` is not in the image;
  it is, so a killswitch is buildable. It stays unbuilt because it would cut
  Claude Code's own API traffic — an honest reason, unlike the previous one.
- `install_feature_skill` rejects path-traversal names, not just blank ones —
  verified `../skills` would have deleted the whole skills directory including
  Mission Control's — and reports `mkdir`/`cp` failures instead of printing a
  success line regardless.
- The usage text ended by printing `set -euo pipefail`, off by one line.
- HOW-TO-USE claimed "the container says so on start". entrypoint prints to
  PID 1's stdout, which no terminal or UI surfaces — `docker logs` appears
  nowhere in the repo. Now points at the migration pre-flight, which does.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -203,7 +203,8 @@ docker exec stdout → tokio task → emit("terminal-output-{sessionId}") → li
 ### Container (`container/`)
 
 - **`Dockerfile`** — Ubuntu 24.04 base with Claude Code, Node.js 22, Python 3.12, Rust, Docker CLI, git, gh, AWS CLI v2, ripgrep, pnpm, uv, ruff pre-installed, plus the shared
-  libraries a browser links against (see below)
+  libraries a browser links against (see below) and the VPN tooling the `vpn_support_enabled`
+  toggle grants capability for (`iproute2`, `wireguard-tools`, `iptables`)
 - **Browser runtime libraries are baked in; browser *binaries* are not.** A layer runs
   `npx --yes playwright@latest install-deps chromium` as root, so Playwright names its own
   dependencies and the list cannot rot against Ubuntu 24.04's `t64` renames or a new Chromium
@@ -307,6 +308,54 @@ container is created once by a very long function where a dropped capability is
   container and make the switch impossible to turn off.
 - Off is byte-identical to a container created before the feature existed, and a missing label
   reads as `false`, so no existing project is churned.
+- **The toggle grants capability and stops there — it routes nothing.** `vpn_host_config()` returns
+  a cap, a device and a sysctl; no client is installed, no route is touched, no tunnel is started
+  or restored. Users read the name as "turn the VPN on" and report the default network not routing
+  through it as a bug. It isn't, and the docs say so explicitly; keep it that way.
+- **The tooling is baked, not installed at runtime.** `iproute2` and `wireguard-tools` are in
+  `container/Dockerfile` because a runtime install lands in the writable layer and is lost on
+  base-image migration — leaving a project holding the capability with nothing able to exercise it,
+  and no error that points at why. `iptables` is deliberately absent; see the Dockerfile comment.
+- **Anything built on this fails open.** The network namespace is rebuilt on every start and no
+  service manager runs inside, so a tunnel never survives stop/start or recreation — while leftover
+  `/run` state makes it look as though it did. Note the two different mechanisms: `/run` is in the
+  writable layer, so on a stop/start it is simply the same container's files, and on a recreation
+  `docker commit` has carried it into the snapshot. Traffic silently reverts to the real address.
+  Any future autostart or killswitch work starts here.
+- **`/run` riding the snapshot means a VPN client's key material can end up in an image.** Verified:
+  a fresh container off the whp snapshot already contained the `wg.priv` a previous tunnel left in
+  `/run`. Anything writing key material there inherits the problem — the same `docker commit`
+  hazard as `triple-c.git-token-hash` and the custom-env fingerprint, in a directory that looks
+  ephemeral and is not. A VPN client that does this should delete its key on teardown.
+- **`iptables` is baked, and picking `nftables` instead would have been wrong.** `Recommends:
+  nftables | iptables` is stripped by `--no-install-recommends`, and `wg-quick` needs a backend for
+  any `AllowedIPs = 0.0.0.0/0`. `nftables` is the tempting choice — preferred by `wg-quick`, half
+  the size — but `wg-quick` picks nft *unconditionally* when present, and its nft ruleset needs
+  `nft_fib_ipv4`, which LinuxKit (Docker Desktop for Mac) does not build while it *does* build
+  `xt_CONNMARK`. Shipping nftables would therefore have forfeited Mac. See the Dockerfile comment;
+  the kernel-config evidence is quoted there.
+- **Two `wg-quick` failures remain, and only one is ours to fix.** Full tunnels still need
+  `xt_CONNMARK`, which WSL2 before 6.6 lacks — nothing installable changes that. And every
+  provider's stock config carries a `DNS =` line that fails in `set_dns()` before any routing, so it
+  breaks split tunnels too; `openresolv` has no candidate on noble and `resolvconf` drags in
+  systemd-resolved, so that one is documented rather than fixed. Driving `wg` and `ip route`
+  directly avoids both, which is what the skill does.
+- **The `pia-vpn` skill is installed *and removed* from `VPN_SUPPORT_ENABLED`.** `container/skills/`
+  is baked to `/opt/triple-c-skills` and `install_feature_skill()` in `entrypoint.sh` copies it into
+  `~/.claude/skills/` on every start — refreshed each time, so a fix reaches any project whose base
+  image has the source, and `rm -rf`'d first, so files dropped from a later version do not linger.
+  The removal branch matters as much as the install: `~/.claude` is a persisted volume, so a skill
+  left behind after the toggle goes off would keep instructing an agent to use a capability the
+  container no longer has. Which is also why the variable is sent as `0` rather than omitted (see
+  `vpn_env_var`, tested), and why it is in `RESERVED_ENV_EXACT` — a custom env var of that name
+  could otherwise claim the skill without the capability behind it.
+- **Both halves of that live in the base image, so neither reaches an existing project.** A
+  recreation builds from the project's *own snapshot*, which has no `/opt/triple-c-skills` and no
+  updated `entrypoint.sh`; only a migration or a Reset delivers them. The install path says so out
+  loud rather than returning silently, and `/opt/triple-c-skills` is in `FEATURE_PROBES` so the
+  migration pre-flight lists it as missing. Worth knowing before adding anything else behind an
+  existing toggle: the label fingerprints *the setting*, not the set of things the setting drives,
+  so a project already at `true` gets no recreation at all on upgrade.
 
 ### Container Lifecycle
 

HOW-TO-USE.md

@@ -477,8 +477,30 @@ When enabled, the container is given the three things a VPN client needs to buil
 the `NET_ADMIN` capability, the `/dev/net/tun` device, and the `net.ipv4.conf.all.src_valid_mark`
 sysctl that WireGuard requires. This is **off by default**.
 
-Without it, a client such as PIA, WireGuard or OpenVPN installs and its daemon starts normally, but
-the connection attempt **hangs until it times out** — a default container has no tun device to open
+The `ip`, `wg` and `iptables` commands ship in the container image so there is something able to use
+them. If your project's container was created from an older base image it will not have them, and
+`wg` will simply not be found — **migrating the project onto the current base image** is what picks
+them up. `sudo apt install iproute2 wireguard-tools iptables` works in the meantime, but lives in
+the writable layer, so it is undone by a **Reset** and by a migration.
+
+**This setting makes a tunnel possible; it does not make one.** Nothing is connected, no traffic is
+redirected, and no tunnel is configured or started on your behalf. Enabling it and expecting the
+container's traffic to start leaving through a VPN is the most common misreading of what it does —
+configuring a tunnel and routing traffic into it remains yours to do.
+
+To make that second half easier, enabling this also installs a **`pia-vpn` skill** into the
+container's `~/.claude/skills/`, so Claude Code can bring up a Private Internet Access tunnel over
+WireGuard for you — ask it to connect the VPN and it will. The skill carries the parts that are
+easy to get wrong (see the DNS note below), and it is removed again when you turn the setting off.
+It needs your PIA credentials in `~/pia-creds`, two lines, username then password. If you use a
+different provider, ignore it and set up your own client; nothing else depends on it.
+
+Like the VPN tooling above, the skill ships in the container image, so a project whose container
+predates it will not get one by toggling the setting — **migrate the project** and it appears; the
+migration pre-flight lists it among what you would gain.
+
+With the setting **off**, a client such as PIA or OpenVPN installs and its daemon starts normally,
+but the connection attempt **hangs until it times out** — a default container has no tun device to open
 and no permission to add an interface or a route, and most clients report that as a generic timeout
 rather than a permissions error.
 
@@ -497,6 +519,39 @@ Things worth knowing:
   **start**, with an error naming `/dev/net/tun` and pointing back at this setting.
 - A VPN client's kill switch applies to everything in the container, Claude Code included. If the
   tunnel drops, expect API calls to fail until it reconnects or the kill switch is turned off.
+- **No tunnel survives a restart.** The network namespace is built fresh every time the container
+  starts, and there is no service manager inside to reconnect anything. Leftover state under `/run`
+  makes it *look* like the tunnel is still configured — that directory is in the container's
+  writable layer, so it is simply still there after a stop/start, and `docker commit` carries it
+  into the snapshot that a recreation is built from. Either way the interface and its routes are
+  gone and traffic goes out your real address again, with no error and nothing visibly different.
+  Re-establish it after every start, and check rather than assume.
+- **A full tunnel breaks DNS unless the client is told to leave private ranges alone.** Your
+  resolver is whatever `/etc/resolv.conf` says, and if that address is outside the container's own
+  subnet then a default route of `0.0.0.0/0` — or a `0.0.0.0/1` plus `128.0.0.0/1` pair — captures
+  it and sends every lookup into a tunnel that cannot carry it. Under Docker Desktop it is
+  `192.168.65.7`, which is exactly that case; on a user-defined Docker network it is `127.0.0.11`,
+  which is loopback and unaffected. Check yours rather than assuming. The symptom when it bites is
+  total: Claude Code reports it cannot connect, because it cannot resolve `api.anthropic.com`.
+  Route `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` and `169.254.0.0/16` via the original
+  gateway — and give the tunnel a resolver it can actually reach, normally the VPN provider's own,
+  or you have a tunnel that leaks every DNS query outside itself. Also pin the VPN endpoint's own
+  address via the original gateway, or the tunnel's encrypted packets try to route through the
+  tunnel. Note that a health check which fetches an IP literal such as `1.1.1.1` passes cleanly
+  while DNS is broken — resolve a name instead.
+- **Delete a client's key material when you tear a tunnel down.** Anything written under `/run` is
+  in the container's writable layer, and recreating or migrating the project runs `docker commit`
+  over it — so a WireGuard private key left there gets baked into the project's snapshot image and
+  copied forward from then on. This is not hypothetical; it has already happened here.
+- **Strip the `DNS =` line from a provider's `.conf` before `wg-quick up`.** Every commercial
+  provider ships one, and `wg-quick` hands it to `resolvconf`, which is not installed — so it fails
+  at `resolvconf: command not found` and deletes the interface again. This happens before any
+  routing, so it takes **split tunnels down too**. Set the resolver another way instead, or drive
+  `wg` and `ip route` directly rather than going through `wg-quick`.
+- **`wg-quick` full tunnels also need `xt_CONNMARK` from the host kernel.** Native Linux, Docker
+  Desktop for Mac and WSL2 kernels from 6.6 have it; older WSL2 kernels do not, and a container
+  cannot load one. There the answer is again to add the routes yourself with `ip route`, which
+  needs no firewall backend on any platform.
 
 > This setting can only be changed when the container is stopped. Capabilities and devices are
 > fixed when a container is created, so toggling it recreates the container on the next start.
@@ -1256,6 +1311,7 @@ The sandbox container (Ubuntu 24.04) comes pre-installed with:
 | ruff | Latest | Python linter/formatter |
 | Rust | Stable | Rust development (via rustup) |
 | Docker CLI | Latest | Container management (when spawning is enabled) |
+| iproute2, WireGuard tools, iptables | Latest | Building a tunnel (when VPN Support is enabled) |
 | git | Latest | Version control |
 | GitHub CLI (gh) | Latest | GitHub integration |
 | AWS CLI | v2 | AWS services and Bedrock |

app/src-tauri/src/docker/container.rs

@@ -233,6 +233,7 @@ const RESERVED_ENV_EXACT: &[&str] = &[
     "MCP_SERVERS_JSON",
     "CLAUDE_CODE_SETTINGS_JSON",
     "MISSION_CONTROL_ENABLED",
+    "VPN_SUPPORT_ENABLED",
     "TRIPLE_C_PERMISSION_MODE",
     CLAUDE_OAUTH_TOKEN_ENV,
     // The model-alias vars are already covered by the `ANTHROPIC_` prefix
@@ -840,6 +841,23 @@ type VpnHostConfigParts = (
 /// host-kernel module auto-loading. It is also enough to flush netfilter rules
 /// inside the container, so pair it with `sandbox_mode_enabled` advisedly.
 /// Hence opt-in, per project, rather than on for everyone.
+/// The env var `entrypoint.sh` installs and removes the `pia-vpn` skill from.
+///
+/// **Emitted either way, never omitted.** `~/.claude` is a persisted volume, so
+/// turning the toggle off has to actively tell entrypoint to remove a skill an
+/// earlier run left there, and an absent variable cannot say that. It is also
+/// what stops a `=1` baked into a snapshot by `docker commit` from outliving
+/// the setting — the explicit `=0` overwrites it.
+///
+/// Extracted for the same reason as [`vpn_host_config`]: the emitting code sits
+/// in a very long function where a dropped or inverted value is invisible, and
+/// `MISSION_CONTROL_ENABLED` twenty lines above shows the failure this avoids —
+/// it is pushed only when true, so a snapshot's baked `=1` survives the toggle
+/// going off.
+fn vpn_env_var(enabled: bool) -> String {
+    format!("VPN_SUPPORT_ENABLED={}", u8::from(enabled))
+}
+
 fn vpn_host_config(enabled: bool) -> VpnHostConfigParts {
     if !enabled {
         return (None, None, None);
@@ -1275,6 +1293,8 @@ pub async fn create_container(
         env_vars.push("MISSION_CONTROL_ENABLED=1".to_string());
     }
 
+    env_vars.push(vpn_env_var(project.vpn_support_enabled));
+
     // Permission mode — read by triple-c-task-runner for scheduled (headless)
     // Claude Code runs. Interactive terminals get the flags directly instead.
     env_vars.push(format!(
@@ -2789,6 +2809,34 @@ mod tests {
         assert_eq!(cap_add.unwrap(), vec!["NET_ADMIN"]);
     }
 
+    #[test]
+    fn the_vpn_skill_flag_is_emitted_either_way_never_omitted() {
+        // The whole removal path depends on this. If `false` ever became "emit
+        // nothing", a project that had the toggle on would keep the skill
+        // forever: the container recreates from a snapshot whose baked
+        // VPN_SUPPORT_ENABLED=1 would then go unchallenged, and entrypoint
+        // would reinstall a skill for a capability the container no longer has.
+        assert_eq!(vpn_env_var(true), "VPN_SUPPORT_ENABLED=1");
+        assert_eq!(vpn_env_var(false), "VPN_SUPPORT_ENABLED=0");
+    }
+
+    #[test]
+    fn the_vpn_skill_flag_is_reserved_from_custom_env() {
+        // entrypoint.sh installs and removes the pia-vpn skill from this
+        // variable. A custom env var of the same name would let a project claim
+        // the skill without the capability behind it — or keep it after the
+        // toggle is off — so it has to be unsettable like the others.
+        assert!(is_reserved_env_key("VPN_SUPPORT_ENABLED"));
+        assert!(is_reserved_env_key("vpn_support_enabled"));
+        assert_eq!(
+            compute_env_fingerprint(&[EnvVar {
+                key: "VPN_SUPPORT_ENABLED".to_string(),
+                value: "1".to_string(),
+            }]),
+            ""
+        );
+    }
+
     /// What bollard actually hands us when a tun-less host rejects the device.
     ///
     /// Captured verbatim from Docker 29.7: `docker create` with a missing

app/src-tauri/src/docker/migration.rs

@@ -135,6 +135,8 @@ pub const FEATURE_PROBES: &[(&str, &str)] = &[
     ("/usr/local/bin/triple-c-task-runner", "Scheduled task runner"),
     ("/usr/local/bin/triple-c-sso-refresh", "AWS SSO auto-refresh"),
     ("/opt/mission-control", "Mission Control (Flight Control)"),
+    ("/usr/bin/wg", "VPN tooling (WireGuard, for the VPN Support toggle)"),
+    ("/opt/triple-c-skills", "Bundled skills (PIA VPN, for the VPN Support toggle)"),
 ];
 
 /// Headroom demanded on Docker's storage backend on top of the measured

container/Dockerfile

@@ -34,6 +34,9 @@ RUN for i in 1 2 3 4 5; do \
     cron \
     bubblewrap \
     socat \
+    iproute2 \
+    wireguard-tools \
+    iptables \
     && rm -rf /var/lib/apt/lists/*
 
 # `libnss3-tools` above provides `certutil`. Chrome/Chromium read neither
@@ -42,6 +45,76 @@ RUN for i in 1 2 3 4 5; do \
 # corporate CA, no matter what the system trust store says. entrypoint.sh
 # degrades to a warning if it is ever missing.
 
+# `iproute2`, `wireguard-tools` and `iptables` above are what the VPN support
+# toggle (`vpn_support_enabled`) grants capability *for*. That toggle hands a
+# project CAP_NET_ADMIN and /dev/net/tun; without `ip` there is then no way to
+# add a route, and without `wg` no way to build the tunnel those two exist to
+# serve — a capability with nothing able to use it.
+#
+# They are baked rather than left to a runtime `apt-get install` for the same
+# reason as the Playwright libraries below: the writable layer is re-paid after
+# every Reset and lost on base-image migration. A hand-installed `wg` therefore
+# works right up until an upgrade, then disappears and takes the tunnel with it
+# — silently, since a VPN that fails to come up looks exactly like one that was
+# never started.
+#
+# Measured against the *current base image*, since a bare ubuntu:24.04 also
+# pulls libelf1t64 and netbase, which this base already has, and so over-reports
+# by ~258 kB: **+12 packages, 7,203 kB on amd64**. The same set on arm64 is
+# ~14.4 MB — the package list is identical on both arches, the binaries are
+# simply larger (measured as 14.7 MB on arm64 ubuntu:24.04, less that 258 kB).
+#
+# ## Why `iptables`, and not `nftables`
+#
+# `wireguard-tools` declares `Recommends: nftables | iptables`, which the
+# `--no-install-recommends` above strips. That is not cosmetic: `wg-quick`'s
+# `add_default()` runs whenever a config has `AllowedIPs = 0.0.0.0/0` — i.e.
+# every stock full-tunnel config every provider hands out — and it shells out to
+# a firewall backend with no `type -p` guard. Measured with neither installed:
+#
+#     [#] iptables-restore -n
+#     /usr/bin/wg-quick: line 32: iptables-restore: command not found
+#     wg-quick EXIT=127
+#
+# `nftables` looks like the better pick — wg-quick prefers it, it is first in
+# that Recommends, it is half the size — and it is the wrong one. wg-quick picks
+# nft *unconditionally* when present (`if type -p nft`, line 241), so installing
+# it makes the iptables path unreachable; and its nft ruleset needs three
+# expression families where the iptables path needs one. Isolating them on a
+# WSL2 host, the two connmark rules install fine and this is what fails:
+#
+#     nft add rule ... fib saddr type != local drop
+#     Error: Could not process rule: No such file or directory
+#                                   ^^^^^^^^^^^^^^  needs nft_fib_ipv4
+#
+# That matters because of how the two hosts we ship to are configured. From
+# LinuxKit's kernel config — Docker Desktop for Mac, identical on both arches:
+#
+#     CONFIG_NETFILTER_XT_CONNMARK=y      <- the iptables path works
+#     # CONFIG_NFT_FIB_IPV4 is not set    <- the nft path does not
+#
+# So shipping `nftables` would forfeit the platform it was meant to fix. With
+# `iptables`, full tunnels work on native Linux, on Docker Desktop for Mac, and
+# on WSL2 kernels from 6.6 (which added xt_CONNMARK as a module). Only WSL2
+# older than that is left out, and nothing installable here changes it — the way
+# out there is to add the routes with `ip route` instead of using `wg-quick`,
+# which is what the pia-vpn skill does on every platform.
+#
+# ## What this still does not fix
+#
+# `wireguard-tools` only *Suggests* `openresolv | resolvconf`, so neither is
+# installed, and every provider's stock config carries a `DNS =` line. That
+# fails in `set_dns()`, *before* the firewall step, so it takes split tunnels
+# down too:
+#
+#     [#] resolvconf -a wg0 -m 0 -x
+#     /usr/bin/wg-quick: line 32: resolvconf: command not found
+#
+# Deliberately not fixed here: `openresolv` has no installation candidate on
+# noble, and `resolvconf` resolves only by pulling in systemd-resolved — a
+# resolver daemon and systemd units, into a container with no systemd. Strip the
+# `DNS =` line and set the resolver another way. Documented in HOW-TO-USE.md.
+
 # Remove default ubuntu user to free UID 1000 for host-user remapping
 RUN if id ubuntu >/dev/null 2>&1; then userdel -r ubuntu 2>/dev/null || userdel ubuntu; fi \
     && if getent group ubuntu >/dev/null 2>&1; then groupdel ubuntu 2>/dev/null || true; fi
@@ -314,6 +387,17 @@ RUN chmod +x /usr/local/bin/triple-c-sso-refresh
 
 COPY mission-control /opt/mission-control
 
+# Skills that ship with a Triple-C feature rather than with Mission Control.
+# entrypoint.sh installs them into ~/.claude/skills/ when the feature that owns
+# them is enabled, and removes them when it is not — a skill telling an agent to
+# build a tunnel in a container that no longer has CAP_NET_ADMIN is worse than
+# no skill at all. Staged in /opt because ~/.claude is a volume mount: an image
+# copy underneath it would be masked from the project's first start onward.
+COPY skills /opt/triple-c-skills
+# `find`, not a `*/*.sh` glob: the glob fails the build the day a skill ships
+# without a script, which is a legitimate thing for a skill to do.
+RUN find /opt/triple-c-skills -name '*.sh' -exec chmod +x {} +
+
 COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh
 COPY triple-c-scheduler /usr/local/bin/triple-c-scheduler

container/entrypoint.sh

@@ -338,6 +338,64 @@ if [ "$MISSION_CONTROL_ENABLED" = "1" ]; then
     unset MISSION_CONTROL_ENABLED
 fi
 
+# ── Feature skills ──────────────────────────────────────────────────────────
+# Skills owned by a Triple-C feature rather than by Mission Control. Installed
+# when the feature is on, removed when it is off: ~/.claude is a persisted
+# volume, so a skill left behind after its feature is disabled would keep
+# telling an agent to use a capability the container no longer has.
+#
+# Copied on every start rather than only when absent, so a fix to a skill
+# reaches projects that already have the old copy. Local edits under these
+# directories do not survive — treat /opt/triple-c-skills as the source.
+#
+# The source lives in the *base image*, so a project whose container predates it
+# recreates from its own snapshot and has no /opt/triple-c-skills to copy from.
+# That case says so rather than returning silently: the toggle is on, the
+# capability is there, and the skill simply never appears — which is impossible
+# to work out from the outside.
+install_feature_skill() {
+    local _name="$1"
+    local _enabled="$2"
+    local _src="/opt/triple-c-skills/$1"
+    local _dest="/home/claude/.claude/skills/$1"
+
+    # Reject anything that is not a plain directory name. The disabled branch
+    # `rm -rf`s $_dest under a *persisted volume*, so a blank name would take the
+    # whole skills directory (Mission Control's included) and `../x` would escape
+    # it entirely. Only the literal `pia-vpn` is passed today; this is so that
+    # stays true.
+    case "$_name" in
+        ''|*/*|.*) echo "entrypoint: install_feature_skill: bad skill name '$_name'"; return 1 ;;
+    esac
+
+    if [ "$_enabled" = "1" ]; then
+        if [ ! -d "$_src" ]; then
+            echo "entrypoint: $_name skill unavailable — this container's base image predates it; migrate the project to get it"
+            return 0
+        fi
+        # Checked, not assumed: with no `set -e` in this script every step here
+        # can fail (full volume, read-only mount, a file where the directory
+        # should be) and the success line would still print.
+        mkdir -p /home/claude/.claude/skills || {
+            echo "entrypoint: $_name skill install FAILED (cannot create ~/.claude/skills)"; return 1; }
+        # Not just $_dest: when Mission Control is off nothing else creates the
+        # parent, so root would own it and `claude` could not add a skill there.
+        chown claude:claude /home/claude/.claude/skills
+        rm -rf "$_dest"
+        cp -r "$_src" "$_dest" || {
+            echo "entrypoint: $_name skill install FAILED (copy from $_src)"; return 1; }
+        chown -R claude:claude "$_dest"
+        echo "entrypoint: $_name skill installed to ~/.claude/skills/"
+    elif [ -e "$_dest" ] || [ -L "$_dest" ]; then
+        # -e/-L rather than -d: a leftover *file* at that path must go too.
+        rm -rf "$_dest"
+        echo "entrypoint: $_name skill removed (feature disabled)"
+    fi
+}
+
+install_feature_skill pia-vpn "${VPN_SUPPORT_ENABLED:-0}"
+unset VPN_SUPPORT_ENABLED
+
 # ── Claude Code settings ────────────────────────────────────────────────────
 # Merge Claude Code settings into ~/.claude/settings.json (preserves existing
 # keys). Creates the file if it doesn't exist. These control TUI mode, effort

container/skills/pia-vpn/SKILL.md

@@ -0,0 +1,225 @@
+---
+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` — three 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: 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* every network fetch has succeeded, so a
+failed `up` leaves an existing tunnel alone rather than tearing it down to
+report a bad password. 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.

container/skills/pia-vpn/pia-wg.sh

@@ -0,0 +1,318 @@
+#!/usr/bin/env bash
+# PIA over WireGuard, headless.
+#
+# PIA's desktop client (pia-daemon + piactl) cannot work here: its daemon never
+# accepts a client connection without the GUI running, and `piactl --help` says
+# as much. This talks to PIA's public API directly instead, which is the path
+# PIA themselves document for headless use.
+#
+#   sudo pia-wg.sh up          tunnel up, only 1.1.1.1 routed through it (safe test)
+#   sudo pia-wg.sh up --full   tunnel up, all *public* traffic exits via PIA
+#   sudo pia-wg.sh down        tear down, restoring DNS and routes
+#   sudo pia-wg.sh status      handshake, DNS and current public IP
+#
+# Requires the project's "VPN support" setting (Config -> Runtime) to be on.
+#
+# Settings are read from the environment, but note that sudo resets it: they
+# have to be passed *through* sudo, after the word `sudo`, not before it.
+#
+#   sudo PIA_REGION=uk_london pia-wg.sh up --full     # works
+#   PIA_REGION=uk_london sudo pia-wg.sh up --full     # silently ignored
+#
+#   PIA_CREDS   credentials file, two lines: username, then password
+#               (default /home/claude/pia-creds; never echoed by this script)
+#   PIA_REGION  region id (default us_chicago). List them with:
+#     curl -s https://serverlist.piaservers.net/vpninfo/servers/v6 \
+#       | head -1 | jq -r '.regions[].id'
+set -euo pipefail
+
+# Not ~/pia-creds: under sudo, HOME is /root.
+# Read by up()'s EXIT trap, which runs after the function's locals are gone.
+SETUP_OK=0
+
+CREDS=${PIA_CREDS:-/home/claude/pia-creds}
+REGION=${PIA_REGION:-us_chicago}
+IFACE=pia0
+STATE=/run/pia-wg
+
+# Kept off the tunnel in --full mode. The container's DNS resolver, the Docker
+# host network (host.docker.internal, any host-side Ollama), sibling containers
+# and the LAN all live in here. PIA cannot route any of it, so without these
+# exclusions the container reaches the public internet and nothing else --
+# including, fatally, its own resolver.
+PRIVATE_NETS="10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16"
+
+# Args are joined with spaces so a long message can be written as several
+# source lines without the indentation ending up in the output.
+die() { echo "pia-wg: $*" >&2; exit 1; }
+
+# `x=$(cmd)` is a plain assignment, so `set -e` kills the script on a non-zero
+# cmd *before* any `[ -z "$x" ] || die` line can run. Every capture below
+# therefore goes through `run`; without it a wrong password exits 22 with no
+# output at all, which is the most likely way this is used wrongly and was the
+# least explained.
+#
+# It takes a description rather than reporting the command it ran: one of these
+# invocations carries the account password in `-u`, and an error message is
+# exactly the wrong place for that to surface.
+run() { local what=$1; shift; "$@" || die "$what (exit $?)"; }
+
+preflight() {
+  [ "$(id -u)" = 0 ] || die "run with sudo"
+  # CAP_NET_ADMIN is bit 12. Checking it by name gives a usable error; without
+  # it the first `ip` call fails with a bare "Operation not permitted" that
+  # points nowhere near the setting that actually needs changing.
+  #
+  # Deliberately NOT checking /dev/net/tun: kernel WireGuard is a netlink
+  # interface and does not use it (verified -- `ip link add type wireguard`
+  # succeeds with NET_ADMIN and no tun device). It is OpenVPN and userspace
+  # wireguard-go that need it. The real kernel dependency here is the
+  # `wireguard` module, which `ip link add` below reports on directly.
+  local caps
+  caps=$(awk '/^CapEff:/{print $2}' /proc/self/status)
+  if [ $(( 0x$caps & 0x1000 )) -eq 0 ]; then
+    die "this container has no CAP_NET_ADMIN." \
+        "Turn on \"VPN support\" in Config -> Runtime and start the project" \
+        "again. That recreates the container; the home and .claude volumes" \
+        "are preserved, so nothing in them is lost."
+  fi
+  command -v wg >/dev/null || \
+    die "wireguard-tools is not installed." \
+        "If this project's container was built from an older base image," \
+        "migrate it onto the current one -- that is what ships \`wg\`."
+  [ -r "$CREDS" ] || \
+    die "no credentials at $CREDS." \
+        "Two lines are expected: username, then password." \
+        "Set PIA_CREDS (after the word \`sudo\`) to read them elsewhere."
+}
+
+# Routes that must work. A silent failure here is the worst state this script
+# can reach: the two half-routes need no gateway and would succeed, so the
+# tunnel captures everything while the exclusions that keep DNS and the Docker
+# host reachable are quietly missing -- and `status` still says "full tunnel".
+add_route() {
+  ip route add "$@" || die "could not add route '$*'"
+  printf '%s\n' "$*" >> "$STATE/routes"
+}
+
+up() {
+  case "${1:-}" in
+    ""|--full) ;;
+    *) die "unknown option '$1' (expected --full or nothing)." \
+           "Refusing rather than silently giving you a test route." ;;
+  esac
+  preflight
+
+  mkdir -p "$STATE"; cd "$STATE"
+
+  # `curl -o` creates the file before it knows the request failed, so a plain
+  # `[ -f ]` cache check can pin a truncated cert forever -- and /run rides the
+  # snapshot, so "forever" outlives the container. Fetch to a temp name and
+  # rename only on success.
+  if [ ! -s ca.rsa.4096.crt ]; then
+    run "could not download PIA's CA certificate" \
+      curl -sf -m 20 -o ca.crt.part \
+      https://raw.githubusercontent.com/pia-foss/manual-connections/master/ca.rsa.4096.crt
+    [ -s ca.crt.part ] || die "PIA's CA certificate downloaded empty"
+    mv ca.crt.part ca.rsa.4096.crt
+  fi
+
+  local u p tok srv sip scn priv pub resp ep gw dns
+  u=$(sed -n 1p "$CREDS"); p=$(sed -n 2p "$CREDS")
+  [ -n "$u" ] && [ -n "$p" ] || die "$CREDS needs two lines: username, then password"
+
+  tok=$(run "PIA rejected the credentials in $CREDS, or could not be reached" \
+    curl -sf -m 25 -u "$u:$p" \
+    https://www.privateinternetaccess.com/gtoken/generateToken | jq -r .token)
+  [ -n "$tok" ] && [ "$tok" != null ] || die "PIA returned no token - check the credentials in $CREDS"
+
+  run "could not fetch PIA's server list" \
+    curl -sf -m 30 https://serverlist.piaservers.net/vpninfo/servers/v6 \
+    | head -1 > servers.json
+  srv=$(jq -r --arg r "$REGION" '.regions[] | select(.id==$r) | .servers.wg[0]' servers.json)
+  sip=$(echo "$srv" | jq -r .ip); scn=$(echo "$srv" | jq -r .cn)
+  [ -n "$sip" ] && [ "$sip" != null ] || die "no WireGuard server for region '$REGION'"
+
+  # Only now tear down any previous tunnel. Doing it up front (as an earlier
+  # version did) meant a failed token fetch or an unreachable server list took
+  # a *working* tunnel down with it and silently reverted the container to its
+  # real address, while the error talked about credentials. Everything above
+  # this line can fail; nothing above it has touched the network stack.
+  #
+  # It also still does the job it was added for: clearing a stale resolv.conf
+  # backup so a second `up` cannot save PIA's own resolvers over the real ones.
+  down >/dev/null 2>&1 || true
+
+  # From here on the network stack is being modified, so any failure has to put
+  # it back rather than exit half-configured. `down` is idempotent and restores
+  # routes and resolv.conf exactly.
+  #
+  # EXIT rather than ERR, and a flag rather than the trap's own exit status: an
+  # ERR trap is not inherited by shell functions without `set -E`, so a failure
+  # inside add_route would not fire it, and `die` exits explicitly, which is not
+  # an error and would not fire it either. EXIT catches both.
+  SETUP_OK=0
+  trap '[ "$SETUP_OK" = 1 ] || { echo "pia-wg: setup failed - rolling back" >&2; down >/dev/null 2>&1; }' EXIT
+
+  # umask, not a later chmod: the file is created under the inherited 0022
+  # otherwise, so the key is world-readable for the moment in between.
+  ( umask 077; priv=$(wg genkey); printf '%s' "$priv" > wg.priv )
+  priv=$(cat wg.priv); pub=$(printf '%s' "$priv" | wg pubkey)
+
+  # The token goes in on stdin as a curl config rather than in the argv, where
+  # `ps` and /proc/*/cmdline expose it to every process in the container --
+  # verified. It is a ~24h bearer credential for the whole PIA account.
+  # PIA pins its certificate to the server's common name, which is why this
+  # connects by CN and lets --connect-to point that name at the real address.
+  resp=$(printf -- '--data-urlencode "pt=%s"\n--data-urlencode "pubkey=%s"\n' "$tok" "$pub" \
+    | run "could not register the key with $scn" \
+        curl -sf -m 25 -G -K - --connect-to "$scn::$sip:" \
+        --cacert ca.rsa.4096.crt "https://$scn:1337/addKey")
+  [ "$(echo "$resp" | jq -r .status)" = OK ] || die "key registration failed: $resp"
+
+  : > "$STATE/routes"
+  ip link add "$IFACE" type wireguard 2>/dev/null || \
+    die "could not create a WireGuard interface." \
+        "The Docker host's kernel has no 'wireguard' module."
+  wg set "$IFACE" private-key wg.priv \
+    peer "$(echo "$resp" | jq -r .server_key)" \
+    endpoint "$(echo "$resp" | jq -r .server_ip):$(echo "$resp" | jq -r .server_port)" \
+    allowed-ips 0.0.0.0/0 persistent-keepalive 25
+  # The kernel holds the key from here, so the file has no reason to outlive
+  # this line -- and every reason not to: /run is in the writable layer, and a
+  # recreate or migrate runs `docker commit` over it without tearing the tunnel
+  # down first, baking the key into the project's snapshot image. `down` also
+  # removes it, for the case where `up` never got this far.
+  rm -f wg.priv
+  ip addr add "$(echo "$resp" | jq -r .peer_ip)/32" dev "$IFACE"
+  ip link set "$IFACE" up
+
+  if [ "${1:-}" = "--full" ]; then
+    ep=$(echo "$resp" | jq -r .server_ip)
+    gw=$(ip route show default | awk '{print $3; exit}')
+    # `default dev eth0` with no `via` yields the literal "eth0" here, which
+    # would make every exclusion below a malformed no-op.
+    [[ $gw =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]] || \
+      die "no usable default gateway to pin the tunnel against (got '${gw:-none}')"
+
+    # PIA's resolvers are required in --full. Without them the 10/8 exclusion
+    # below is already in place, so every lookup would go to the container's
+    # own resolver *outside* the tunnel -- a full tunnel leaking all its DNS,
+    # reported by `status` as perfectly healthy.
+    dns=$(echo "$resp" | jq -r '.dns_servers[]? // empty' | head -2)
+    [ -n "$dns" ] || die "PIA returned no DNS servers; refusing a full tunnel that would leak every lookup"
+
+    # Pin the endpoint to the pre-existing gateway first, so the tunnel's own
+    # packets do not try to route through the tunnel. Then beat the default
+    # route with two half-routes rather than replacing it -- nothing to restore
+    # on teardown, and the container keeps working if this script dies midway.
+    add_route "$ep/32" via "$gw"
+    add_route 0.0.0.0/1 dev "$IFACE"
+    add_route 128.0.0.0/1 dev "$IFACE"
+
+    # Keep container, host and LAN traffic off the tunnel. Longer prefixes than
+    # the two halves above, so these win.
+    for n in $PRIVATE_NETS; do add_route "$n" via "$gw"; done
+
+    # PIA's resolvers live inside 10/8, so pin them back through the tunnel with
+    # /32s -- longer still, so they beat the exclusion just added.
+    cp /etc/resolv.conf "$STATE/resolv.conf.bak"
+    for d in $dns; do add_route "$d/32" dev "$IFACE"; done
+    # resolv.conf is a bind mount: write through it, never replace it.
+    for d in $dns; do echo "nameserver $d"; done > /etc/resolv.conf
+    echo "full tunnel: public traffic exits via PIA; private ranges stay local"
+  else
+    add_route 1.1.1.1/32 dev "$IFACE"
+    echo "test route only: 1.1.1.1 goes via PIA, everything else unchanged"
+  fi
+
+  # A tunnel with no handshake still routes -- into a black hole. Without this
+  # `up --full` would exit 0 having pointed all traffic *and* resolv.conf at a
+  # peer that never answered, and `status` would print "mode: full tunnel".
+  local waited=0
+  until [ "$(wg show "$IFACE" latest-handshakes | awk '{print $2; exit}')" != 0 ]; do
+    waited=$((waited + 1))
+    [ "$waited" -lt 20 ] || die "no handshake from $REGION after 10s - rolled back"
+    sleep 0.5
+  done
+
+  SETUP_OK=1
+  trap - EXIT
+  status
+}
+
+down() {
+  [ "$(id -u)" = 0 ] || die "run with sudo"
+  # Only restore something that actually looks like a resolver file. Restoring
+  # an empty or truncated backup leaves the container with no DNS at all, which
+  # is worse than leaving the current one alone.
+  if [ -f "$STATE/resolv.conf.bak" ]; then
+    if grep -q '^nameserver' "$STATE/resolv.conf.bak" 2>/dev/null; then
+      cat "$STATE/resolv.conf.bak" > /etc/resolv.conf
+    else
+      echo "pia-wg: warning - saved resolv.conf looks empty; leaving the current one alone" >&2
+    fi
+    rm -f "$STATE/resolv.conf.bak"
+  fi
+  if [ -f "$STATE/routes" ]; then
+    # Reverse order: the specific overrides go before the ranges they sit in.
+    tac "$STATE/routes" | while read -r r; do
+      [ -n "$r" ] && ip route del $r 2>/dev/null || true
+    done
+    rm -f "$STATE/routes"
+  fi
+  ip link del "$IFACE" 2>/dev/null || true
+  # /run is in the writable layer and `docker commit` bakes it into the
+  # project's snapshot image, so a key left here rides that image into every
+  # future container. Verified: a snapshot already carried one.
+  rm -f "$STATE/wg.priv"
+  echo "tunnel down"
+}
+
+# Both are Cloudflare and both answer /cdn-cgi/trace over their bare address, so
+# neither needs DNS. Only 1.1.1.1 is ever routed into the tunnel, which is what
+# lets status tell the two exits apart.
+TRACE_TUNNELLED=https://1.1.1.1/cdn-cgi/trace
+TRACE_DIRECT=https://1.0.0.1/cdn-cgi/trace
+
+exit_ip() { curl -s -m 20 "$1" | sed -n 's/^ip=//p'; }
+
+status() {
+  # `wg show` needs root; `ip route`/`ip link` do not. Without this guard an
+  # unprivileged run prints "no tunnel up" and then "mode: full tunnel" in the
+  # same breath, and an agent reading the first line re-runs `up`.
+  [ "$(id -u)" = 0 ] || die "run with sudo"
+  wg show "$IFACE" 2>/dev/null | grep -E "latest handshake|transfer" || echo "no tunnel up"
+
+  # Resolve a name, not an IP literal. A curl to 1.1.1.1 succeeds while DNS is
+  # completely broken, which is exactly how a dead resolver goes unnoticed.
+  printf 'DNS: '
+  if timeout 10 getent hosts api.anthropic.com >/dev/null 2>&1; then
+    echo "ok (via $(sed -n 's/^nameserver //p' /etc/resolv.conf | tr '\n' ' '))"
+  else
+    echo "BROKEN - cannot resolve api.anthropic.com"
+  fi
+
+  # Report the exit per mode. In test mode the probe address is itself the one
+  # thing inside the tunnel, so a single "public IP" line would print a PIA
+  # address while every other packet leaves directly -- the exact reading that
+  # makes a test tunnel look like a full one.
+  if ip route show 0.0.0.0/1 2>/dev/null | grep -q "$IFACE"; then
+    echo "mode: full tunnel"
+    echo "  all traffic exits: $(exit_ip "$TRACE_TUNNELLED")"
+  elif ip link show "$IFACE" >/dev/null 2>&1; then
+    echo "mode: test route only (1.1.1.1 through the tunnel, nothing else)"
+    echo "  through the tunnel: $(exit_ip "$TRACE_TUNNELLED")"
+    echo "  everything else:    $(exit_ip "$TRACE_DIRECT")   <- your real address"
+  else
+    echo "mode: no tunnel"
+    echo "  all traffic exits: $(exit_ip "$TRACE_DIRECT")"
+  fi
+}
+
+case "${1:-}" in
+  up) shift; up "${1:-}" ;;
+  down) down ;;
+  status) status ;;
+  *) sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'; exit 1 ;;
+esac