Let a project's container run a VPN client

A VPN client installed in a container today starts, runs, and then hangs until its connection times out. Nothing reports an error: a default container has no /dev/net/tun to open and no CAP_NET_ADMIN to add an interface or a route with, and clients surface that as a generic timeout rather than a permissions failure. Add an opt-in per-project "VPN support" switch granting the three things a tunnel needs. They are useless individually, which is why vpn_host_config() defines the set in one place and the tests assert all of it: * CAP_NET_ADMIN — Docker's default bounding set has net_raw but not net_admin, so a client can ping but never connect. * /dev/net/tun — passed through from the host so the kernel's tun module backs it, rather than mknod-ed inside. * net.ipv4.conf.all.src_valid_mark — WireGuard's wg-quick sets this and cannot from inside a container, /proc/sys being read-only, so its handshakes are dropped by reverse-path filtering. Off by default and deliberately opt-in: NET_ADMIN lets anything in the container reconfigure that container's network stack. It is namespaced — no authority over the host's interfaces or any other container. Capabilities and devices are fixed when a container is created, so this is container state and takes the label-and-compare treatment. triple-c.vpn-support is written unconditionally, false included, for the usual docker commit reason: a true stamped once would ride the snapshot image into every future container and make the switch impossible to turn back off. A missing label reads as false and off is byte-identical to today, so no existing project is churned. Requesting the device fails at creation when the host kernel has no tun module, which would otherwise surface as a project that simply refuses to start. explain_create_failure() rewrites that one error to name the switch and the Docker-Desktop-VM-versus-your-machine distinction, and leaves every other failure untouched. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 07:52:39 -07:00
12 changed files with 68 additions and 1144 deletions
@@ -39,48 +39,13 @@ jobs:
          MAJOR_MINOR=$(cat VERSION | tr -d '[:space:]')
          echo "Major.Minor: ${MAJOR_MINOR}"
-          # The patch number is **one past the highest patch already used**, and
+          # Find the latest tag matching v{MAJOR_MINOR}.N (exclude -mac, -win suffixes)
-          # never a distance.
+          # `|| true` so an empty grep result doesn't fail the step under pipefail.
-          #
+          LATEST_TAG=$(git tag -l "v${MAJOR_MINOR}.*" --sort=-v:refname | grep -E "^v${MAJOR_MINOR}\.[0-9]+$" | head -1 || true)
          # It used to be `git rev-list --count <highest tag>..HEAD`, which is
          # not a counter at all: it measures how far HEAD has drifted from
          # whichever tag sorts highest, and that resets to zero every time a
          # tag is cut. The published history is the proof — each of these is
          # exactly what the old formula returned at the time:
          #
          #   v0.4.0 -> 3 commits -> v0.4.3    looked fine
          #   v0.4.3 -> 4 commits -> v0.4.4    fine by luck, 4 > 3
          #   v0.4.4 -> 2 commits -> v0.4.2    went backwards
          #   v0.4.4 -> 6 commits -> v0.4.6    jumped, skipping .5
          #   v0.4.6 -> 3 commits -> v0.4.3    already taken; the upload failed
          #
          # Reusing a version is worse than failing to publish one: the macOS
          # and Windows steps replace assets in place, so a duplicate silently
          # rewrote a release that had been public for three days. Monotonic
          # numbering is what stops that at the source.
          #
          # Suffixed tags count too. `create-tag` is skipped when any platform
          # job fails, so a run can publish v0.4.7-mac and never create the
          # plain v0.4.7 — reading only unsuffixed tags would then hand the
          # same number out twice.
          HIGHEST=$(git tag -l "v${MAJOR_MINOR}.*" \
            | grep -E "^v${MAJOR_MINOR}\.[0-9]+(-mac|-win)?$" \
            | sed -E "s/^v${MAJOR_MINOR}\.([0-9]+).*/\1/" \
            | sort -n | tail -1 || true)
-          # A re-run of a commit that already released must not mint a new
+          if [ -n "$LATEST_TAG" ]; then
-          # version just because its own tag now exists.
+            echo "Latest matching tag: ${LATEST_TAG}"
-          EXISTING=$(git tag --points-at HEAD \
+            PATCH=$(git rev-list --count "${LATEST_TAG}..HEAD")
            | grep -E "^v${MAJOR_MINOR}\.[0-9]+$" \
            | sed -E "s/^v${MAJOR_MINOR}\.([0-9]+)$/\1/" \
            | sort -n | tail -1 || true)
          if [ -n "$EXISTING" ]; then
            echo "HEAD is already tagged v${MAJOR_MINOR}.${EXISTING} — reusing it"
            PATCH="${EXISTING}"
          elif [ -n "$HIGHEST" ]; then
            echo "Highest patch already used on this line: ${HIGHEST}"
            PATCH=$((HIGHEST + 1))
          else
            # A minor line nobody has tagged yet is a *new* line, and a new line
            # starts at .0 — that is what "we are moving to 0.4.x" means. The
@@ -200,70 +165,21 @@ jobs:
        env:
          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
        run: |
          set -euo pipefail
          TAG="v${{ needs.compute-version.outputs.version }}"
-
+          # Create release
-          # Idempotent get-or-create, matching build-macos. This step used to
+          curl -s -X POST \
          # POST /releases unconditionally: against a tag that already existed
          # Gitea answered 409, the grep below found no id, and the run died
          # with a bare "exitcode '1'" and not one line of output explaining
          # it — `curl -s` with no `-f` swallows the HTTP error, so nothing
          # ever said "409" or "duplicate tag". Hence -fsS throughout, and
          # pipefail so a failure cannot be stepped over.
          HTTP_CODE=$(curl -sS -o release.json -w '%{http_code}' \
            -H "Authorization: token ${TOKEN}" \
-            "${GITEA_URL}/api/v1/repos/${REPO}/releases/tags/${TAG}")
+            -H "Content-Type: application/json" \
-          case "${HTTP_CODE}" in
+            -d "{\"tag_name\": \"${TAG}\", \"name\": \"Triple-C ${TAG} (Linux)\", \"body\": \"Automated build from commit ${{ gitea.sha }}\"}" \
-            200)
+            "${GITEA_URL}/api/v1/repos/${REPO}/releases" > release.json
-              echo "Release ${TAG} already exists, reusing"
+          RELEASE_ID=$(cat release.json | grep -o '"id":[0-9]*' | head -1 | grep -o '[0-9]*')
              ;;
            404)
              echo "Creating release ${TAG}"
              curl -fsS -X POST \
                -H "Authorization: token ${TOKEN}" \
                -H "Content-Type: application/json" \
                -d "{\"tag_name\": \"${TAG}\", \"name\": \"Triple-C ${TAG} (Linux)\", \"body\": \"Automated build from commit ${{ gitea.sha }}\"}" \
                "${GITEA_URL}/api/v1/repos/${REPO}/releases" > release.json
              ;;
            *)
              echo "Unexpected ${HTTP_CODE} looking up release ${TAG}:" >&2
              cat release.json >&2
              exit 1
              ;;
          esac
          RELEASE_ID=$(python3 -c "import json,sys; print(json.load(open('release.json')).get('id',''))")
          if [ -z "${RELEASE_ID}" ]; then
            echo "No release id for ${TAG}; refusing to upload into nothing:" >&2
            cat release.json >&2
            exit 1
          fi
          echo "Release ID: ${RELEASE_ID}"
-
+          # Upload each artifact
          # Replace-not-conflict, so a retry after a partial upload succeeds.
          # Versions are monotonic now (see compute-version), so this can only
          # ever be replacing an asset from a failed run of this same commit —
          # never one belonging to an already-published version.
          for file in artifacts/*; do
            [ -f "$file" ] || continue
            filename=$(basename "$file")
            EXISTING_ID=$(curl -sS \
              -H "Authorization: token ${TOKEN}" \
              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets" \
              | python3 -c "import json,sys; t=sys.argv[1]; print(next((a['id'] for a in json.load(sys.stdin) if a.get('name')==t), ''))" "${filename}" || true)
            if [ -n "${EXISTING_ID}" ]; then
              echo "Deleting existing asset ${filename} (id ${EXISTING_ID})"
              curl -fsS -X DELETE \
                -H "Authorization: token ${TOKEN}" \
                "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets/${EXISTING_ID}"
            fi
            echo "Uploading ${filename}..."
-            curl -fsS --http1.1 \
+            curl -s -X POST \
              --retry 5 --retry-all-errors --retry-delay 5 \
              --max-time 600 \
              -X POST \
              -H "Authorization: token ${TOKEN}" \
              -H "Content-Type: application/octet-stream" \
              --data-binary "@${file}" \
@@ -203,8 +203,7 @@ 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) and the VPN tooling the `vpn_support_enabled`
+  libraries a browser links against (see below)
  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
@@ -288,74 +287,15 @@ container is created once by a very long function where a dropped capability is
  Any two without the third still presents as a connection that hangs to a timeout, which is why
  the tests assert the whole set.
 - **The device is passed through from the host, never `mknod`-ed inside.** The kernel's `tun`
-  module has to back it.
+  module has to back it. When the host has no such device the failure lands at *creation* — the
- **A missing device fails at `start`, not `create` — verified against Docker 29.7.** `docker
+  project simply won't start — so `explain_create_failure()` rewrites that one error to name the
-  create --device /dev/does-not-exist` succeeds and prints an id; runc resolves the device (and
+  switch and the Docker-Desktop-VM-vs-your-machine distinction. Do not let it degrade to a raw
-  validates sysctls) only when it builds the container. So the guard belongs on the start path:
+  bollard string.
  `explain_container_failure()` covers both and is called from `start_container`, where it has a
  container id and no project — which is why it keys off the error naming `/dev/net/tun` rather
  than off `vpn_support_enabled`. Nothing else in Triple-C requests a device, so that is
  unambiguous. A version of this check wired to `create` alone is dead code that looks correct.
 - **`NET_ADMIN` here is not user-namespaced.** Docker does not enable userns remapping by default,
  so only the *network* namespace confines it: no reach onto host interfaces, but promiscuous
  mode, arbitrary addresses/routes/NAT on the shared `docker0` segment (sibling containers, the
  LiteLLM gateway among them, are ARP-spoofable), netlink-triggered host module auto-load, and
  enough authority to flush in-container netfilter rules that sandbox mode may rely on. Keep the
  code comments honest about this — an earlier draft claimed it "confers no authority" outside the
  container, which is too strong.
 - **`triple-c.vpn-support` is written unconditionally, including `false`.** The usual
  `docker commit` reason: a `true` stamped once would ride the snapshot image into every future
  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
@@ -477,81 +477,21 @@ 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**.
-The `ip`, `wg` and `iptables` commands ship in the container image so there is something able to use
+Without it, a client such as PIA, WireGuard, OpenVPN or Tailscale installs and its daemon starts
-them. If your project's container was created from an older base image it will not have them, and
+normally, but the connection attempt **hangs until it times out** — a default container has no tun
-`wg` will simply not be found — **migrating the project onto the current base image** is what picks
+device to open and no permission to add an interface or a route, and most clients report that as a
-them up. `sudo apt install iproute2 wireguard-tools iptables` works in the meantime, but lives in
+generic timeout rather than a permissions error.
 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.
 Things worth knowing:
- Tailscale is the exception: in its `--tun=userspace-networking` mode it needs neither the
+- `NET_ADMIN` applies to the container's **own** network namespace. It confers no authority over
-  capability nor the device, so leave this off if that is all you want.
+  the host's interfaces or over any other container. It does mean anything running in the
-
+  container can reconfigure that namespace, which is why it is opt-in.
 - `NET_ADMIN` applies to the container's **own** network namespace — it cannot touch the host's
  interfaces. It is not nothing, though: within that namespace anything in the container can set
  promiscuous mode and add arbitrary addresses, routes and firewall rules on the Docker bridge it
  shares with your other containers, and it can flush firewall rules that sandbox mode relies on.
  Grant it per project, to projects that need it.
 - The **Docker host's** kernel must have the `tun` module available. With Docker Desktop that is
-  the Linux VM, not your own machine. If it is missing, the container is created but fails to
+  the Linux VM, not your own machine. If it is missing, the container fails to create with an
-  **start**, with an error naming `/dev/net/tun` and pointing back at this setting.
+  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.
@@ -1311,7 +1251,6 @@ 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 |
@@ -233,7 +233,6 @@ 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
@@ -831,33 +830,8 @@ type VpnHostConfigParts = (
 ///   its handshake packets are dropped by reverse-path filtering. Harmless for
 ///   OpenVPN-based clients, so it is set unconditionally with the rest.
 ///
-/// What it costs, stated accurately: Docker does not enable user-namespace
+/// This is namespaced to the container's own network stack: `NET_ADMIN` confers
-/// remapping by default, so this is a real `CAP_NET_ADMIN` in the *initial*
+/// no authority over the host's interfaces or over any other container.
 /// user namespace and only the **network** namespace confines it. It cannot
 /// touch the host's interfaces, but within its own namespace it can set
 /// promiscuous mode and add arbitrary addresses, routes and NAT rules on the
 /// shared `docker0` L2 segment — which puts sibling containers (the LiteLLM
 /// gateway among them) within reach of ARP spoofing, and lets netlink trigger
 /// 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);
@@ -883,42 +857,31 @@ fn vpn_host_config(enabled: bool) -> VpnHostConfigParts {
 /// Turn the daemon's device-passthrough failure into an explanation.
 ///
-/// **This fires on `start`, not `create`.** Verified against Docker 29.7:
+/// Requesting `/dev/net/tun` fails at *creation* when the host kernel has no
-/// `docker create --device /dev/does-not-exist` succeeds and prints an id; the
+/// `tun` module — and the raw bollard error names a path the user will look for
-/// device is only resolved when runc builds the container, so the failure lands
+/// on the wrong machine, since with Docker Desktop the relevant host is the
-/// on the *next* call. Sysctls validate at the same point. Anything that
+/// Linux VM rather than their own. Left unmapped this surfaces as a project
-/// inspects only the create path will never see it — which is why both paths
+/// that simply refuses to start, with nothing pointing back at the switch that
-/// route through here and the tests exercise the start-side string.
+/// caused it.
-///
+fn explain_create_failure(err: &str, vpn_enabled: bool) -> String {
-/// Unmapped, this reads as `Failed to start container: Docker responded with
+    let device_missing = vpn_enabled
-/// status code 500: error gathering device information while adding custom
+        && err.contains(TUN_DEVICE)
 /// device "/dev/net/tun": no such file or directory` — a path the user will go
 /// looking for on the wrong machine, since with Docker Desktop the relevant
 /// host is the Linux VM rather than their own, and with nothing pointing back
 /// at the switch that caused it.
 ///
 /// Deliberately not gated on `vpn_support_enabled`: nothing else in Triple-C
 /// ever asks for a device, so an error naming `/dev/net/tun` can only have come
 /// from a container created with the switch on. That keeps the check usable
 /// from [`start_container`], which has a container id and no project.
 fn explain_container_failure(action: &str, err: &str) -> String {
    let device_missing = err.contains(TUN_DEVICE)
        && (err.contains("no such file or directory")
            || err.contains("No such file or directory")
            || err.contains("error gathering device information"));
    if device_missing {
        return format!(
-            "Failed to {} container: the Docker host has no {} device, which \
+            "Failed to create container: the Docker host has no {} device, which \
             \"VPN support\" requires. The host kernel needs the `tun` module \
             loaded (on Docker Desktop that is the Linux VM, not your own \
             machine). Turn VPN support off in Config → Runtime to start this \
             project without it. Original error: {}",
-            action, TUN_DEVICE, err
+            TUN_DEVICE, err
        );
    }
-    format!("Failed to {} container: {}", action, err)
+    format!("Failed to create container: {}", err)
 }
 pub async fn create_container(
@@ -1293,8 +1256,6 @@ 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!(
@@ -1613,7 +1574,7 @@ pub async fn create_container(
    let response = docker
        .create_container(Some(options), config)
        .await
-        .map_err(|e| explain_container_failure("create", &e.to_string()))?;
+        .map_err(|e| explain_create_failure(&e.to_string(), project.vpn_support_enabled))?;
    Ok(response.id)
 }
@@ -1623,7 +1584,7 @@ pub async fn start_container(container_id: &str) -> Result<(), String> {
    docker
        .start_container(container_id, None::<StartContainerOptions<String>>)
        .await
-        .map_err(|e| explain_container_failure("start", &e.to_string()))
+        .map_err(|e| format!("Failed to start container: {}", e))
 }
 pub async fn stop_container(container_id: &str) -> Result<(), String> {
@@ -2810,80 +2771,30 @@ mod tests {
    }
    #[test]
-    fn the_vpn_skill_flag_is_emitted_either_way_never_omitted() {
+    fn a_missing_tun_device_is_explained_rather_than_echoed() {
-        // The whole removal path depends on this. If `false` ever became "emit
+        let raw = "error gathering device information while adding custom device \
-        // nothing", a project that had the toggle on would keep the skill
+                   \"/dev/net/tun\": no such file or directory";
-        // forever: the container recreates from a snapshot whose baked
+        let msg = explain_create_failure(raw, true);
        // 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
    /// device **succeeds**, and this arrives from the subsequent `start`.
    /// `DockerResponseServerError`'s Display is
    /// `"Docker responded with status code {code}: {message}"` with the
    /// daemon's message unaltered.
    const REAL_TUN_ERROR: &str = "Docker responded with status code 500: error \
        gathering device information while adding custom device \
        \"/dev/net/tun\": no such file or directory";
    #[test]
    fn a_missing_tun_device_is_explained_on_the_path_that_actually_fails() {
        // The start path is the one that matters: the daemon defers device
        // resolution to runc, so create returns an id on a host with no tun
        // module and only start fails. A version of this that checked create
        // alone would be dead code.
        let msg = explain_container_failure("start", REAL_TUN_ERROR);
        assert!(msg.starts_with("Failed to start container:"), "{}", msg);
        assert!(msg.contains("VPN support"), "should name the switch: {}", msg);
        assert!(msg.contains("tun` module"), "should name the cause: {}", msg);
-        assert!(msg.contains("Config → Runtime"), "should say where to fix it: {}", msg);
+        assert!(msg.contains(raw), "should keep the original error: {}", msg);
        assert!(msg.contains(REAL_TUN_ERROR), "should keep the original: {}", msg);
    }
    #[test]
    fn the_same_explanation_covers_create_if_the_daemon_ever_checks_earlier() {
        // Belt and braces — older and future daemons may validate at create.
        let msg = explain_container_failure("create", REAL_TUN_ERROR);
        assert!(msg.starts_with("Failed to create container:"), "{}", msg);
        assert!(msg.contains("VPN support"), "{}", msg);
    }
    #[test]
    fn unrelated_failures_are_left_alone() {
-        for (action, err) in [
+        // Including a tun error on a project that never asked for VPN support —
-            ("create", "Conflict. The container name \"/triple-c-x\" is already in use"),
+        // that came from somewhere else and must not be misattributed.
-            ("start", "Docker responded with status code 404: No such container"),
+        let name_clash = "Conflict. The container name \"/triple-c-x\" is already in use";
-            ("start", "error gathering device information while adding custom device \"/dev/dri/card0\""),
+        assert_eq!(
-        ] {
+            explain_create_failure(name_clash, true),
-            assert_eq!(
+            format!("Failed to create container: {}", name_clash)
-                explain_container_failure(action, err),
+        );
-                format!("Failed to {} container: {}", action, err),
+
-                "{} should pass through untouched",
+        let tun_err = "no such file or directory: /dev/net/tun";
-                err
+        assert_eq!(
-            );
+            explain_create_failure(tun_err, false),
-        }
+            format!("Failed to create container: {}", tun_err)
        );
    }
    #[test]
@@ -135,8 +135,6 @@ 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
@@ -148,14 +148,13 @@ pub struct Project {
    /// Grant the container what a VPN client needs to build a tunnel:
    /// `CAP_NET_ADMIN`, the `/dev/net/tun` device, and the WireGuard
    /// `src_valid_mark` sysctl. Without all three a client (PIA, WireGuard,
-    /// OpenVPN) installs and runs but its connection attempt hangs until it
+    /// OpenVPN, Tailscale) installs and runs but its connection attempt hangs
-    /// times out, because it cannot create the tunnel interface or touch the
+    /// until it times out, because it cannot create the tunnel interface or
-    /// routing table.
+    /// touch the routing table.
    ///
    /// Off by default and deliberately opt-in: `NET_ADMIN` lets anything in the
-    /// container reconfigure its own network stack, which reaches further than
+    /// container reconfigure its own network stack, which is a meaningful step
-    /// it sounds — see `vpn_host_config` for what it does and does not confer.
+    /// out of the default sandbox. Unlike `auth_bridge_enabled` this *is*
    /// Unlike `auth_bridge_enabled` this *is*
    /// container state, so it carries a `triple-c.vpn-support` label and is
    /// compared in `container_needs_recreation` — capabilities and devices are
    /// fixed at creation and can only change by recreating the container.
@@ -1,94 +0,0 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, screen, fireEvent } from "@testing-library/react";
 import RuntimeSection from "./RuntimeSection";
 import type { Project } from "../../../../lib/types";
 const baseProject: Project = {
  id: "p1",
  name: "api-server",
  paths: [{ host_path: "/src/api", mount_name: "api" }],
  container_id: null,
  status: "stopped",
  backend: "anthropic",
  bedrock_config: null,
  ollama_config: null,
  llamacpp_config: null,
  openai_compatible_config: null,
  allow_docker_access: false,
  sandbox_mode_enabled: true,
  mission_control_enabled: false,
  auth_bridge_enabled: false,
  browser_view_enabled: false,
  vpn_support_enabled: false,
  use_shared_auth_token: true,
  full_permissions: false,
  permission_mode: null,
  ssh_key_path: null,
  ca_cert_path: null,
  git_token: null,
  git_user_name: null,
  git_user_email: null,
  custom_env_vars: [],
  port_mappings: [],
  claude_instructions: null,
  claude_code_settings: null,
  renamed_session_names: {},
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
 };
 const VPN = "VPN support";
 const save = vi.fn().mockResolvedValue(true);
 function renderSection(over: Partial<Project> = {}, disabled = false) {
  return render(
    <RuntimeSection
      project={{ ...baseProject, ...over }}
      save={save}
      disabled={disabled}
      disabledReason="Container must be stopped to change this setting."
    />,
  );
 }
 describe("RuntimeSection — VPN support toggle", () => {
  beforeEach(() => vi.clearAllMocks());
  it("saves only the VPN flag when switched on", () => {
    renderSection();
    fireEvent.click(screen.getByRole("switch", { name: VPN }));
    expect(save).toHaveBeenCalledWith({ vpn_support_enabled: true });
  });
  it("saves the flag off again, rather than dropping the key", () => {
    // Off has to be written explicitly: the container carries a
    // `triple-c.vpn-support` label either way, and an absent value would leave
    // the capability granted.
    renderSection({ vpn_support_enabled: true });
    fireEvent.click(screen.getByRole("switch", { name: VPN }));
    expect(save).toHaveBeenCalledWith({ vpn_support_enabled: false });
  });
  it("reflects the project's current state", () => {
    renderSection({ vpn_support_enabled: true });
    expect(screen.getByRole("switch", { name: VPN })).toBeChecked();
  });
  it("cannot be changed while the container is running", () => {
    // Capabilities and devices are fixed at creation, so this setting is gated
    // on the container being stopped along with the rest of the tab.
    renderSection({}, true);
    const toggle = screen.getByRole("switch", { name: VPN });
    expect(toggle).toBeDisabled();
    fireEvent.click(toggle);
    expect(save).not.toHaveBeenCalled();
  });
  it("warns that the change recreates the container", () => {
    renderSection();
    expect(
      screen.getByText(/recreates the container on its next start/i),
    ).toBeInTheDocument();
  });
 });
@@ -59,7 +59,7 @@ export default function RuntimeSection({
        <SwitchRow
          label="VPN support"
-          hint="Grants NET_ADMIN and the /dev/net/tun device so a VPN client (PIA, WireGuard, OpenVPN) can build a tunnel inside the container. Without it a client installs and runs but its connection hangs until it times out. Anything in the container can then reconfigure the container's own network stack; the host's is untouched. Changing this recreates the container on its next start — the home and .claude volumes are preserved."
+          hint="Grants NET_ADMIN and the /dev/net/tun device so a VPN client (PIA, WireGuard, OpenVPN, Tailscale) can build a tunnel inside the container. Without it a client installs and runs but its connection hangs until it times out. Anything in the container can then reconfigure the container's own network stack; the host's is untouched."
          control={
            <Toggle
              label="VPN support"
@@ -34,9 +34,6 @@ 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
@@ -45,76 +42,6 @@ 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
@@ -387,17 +314,6 @@ 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
@@ -338,64 +338,6 @@ 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
@@ -1,225 +0,0 @@
 ---
 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.
@@ -1,318 +0,0 @@
 #!/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