Ship a firewall backend, and correct three claims review disproved

Review of #28 found the iptables exclusion was justified by a false premise,
and I confirmed it: `wireguard-tools` declares `Recommends: nftables | iptables`,
`--no-install-recommends` strips it, and `wg-quick`'s add_default() shells out
to a firewall backend with no `type -p` guard. Measured on the image as this PR
shipped it:

    [#] iptables-restore -n
    /usr/bin/wg-quick: line 32: iptables-restore: command not found
    wg-quick EXIT=127

That fires for `AllowedIPs = 0.0.0.0/0` — every stock full-tunnel config from
every provider — not for a desktop client's killswitch as the comment claimed.
Split tunnels are unaffected.

Ship `nftables` rather than `iptables`: wg-quick prefers it (`type -p nft`, so
with both installed iptables is dead weight), it is first in the package's own
Recommends, and it is half the size.

The review's proposed fix stopped there; it does not hold. Adding nftables does
not make wg-quick work on this host, and neither does iptables:

    Warning: Extension CONNMARK revision 0 not supported, missing kernel module?

`Table=auto` routes by fwmark and needs xt_CONNMARK from the *host* kernel.
WSL2 has none and containers have no /lib/modules to load one from. So this
fixes native Linux and Docker Desktop for Mac — which other WHP users are on —
and cannot fix Docker Desktop for Windows, where the answer is to add routes
with `ip route` directly. Documented rather than left to be rediscovered.

Also from review:

- "`ip` and `wg` are always present" was false. A project keeps the base image
  it was first built from, so this reaches new projects only. Reworded to match
  the wording already used for the Playwright libraries, and `/usr/bin/wg` added
  to FEATURE_PROBES so an existing project is *told* it is missing VPN tooling
  and prompted to migrate, rather than finding out via `wg: command not found`.
- "no client is installed" contradicted shipping `wg` four lines earlier. The
  true claim is that no tunnel is configured or started.
- The size figure measured against bare ubuntu:24.04, which over-counts by the
  ~209 kB of libelf1t64 the real base already has, and covered one arch. Now
  measured against the current base on amd64 and stated for arm64 too, per the
  standard CLAUDE.md sets for the Playwright layer.
- `/run` persistence conflated two mechanisms: same-container files on a
  stop/start, `docker commit` on a recreation. Both stated, plus the corollary
  that key material written to /run ends up inside a snapshot image — observed,
  a `wg.priv` was already sitting in one.
- The DNS bullet presented a Docker Desktop address as the general case. Now
  leads with the mechanism, notes 127.0.0.11 on a user-defined network is
  unaffected, and adds the two things the advice omitted: a resolver the tunnel
  can reach (or it leaks every query), and pinning the endpoint via the old
  gateway (or the tunnel routes through itself).

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`, `nftables`)
 - **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
@@ -287,15 +288,51 @@ 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. When the host has no such device the failure lands at *creation* — the
-  project simply won't start — so `explain_create_failure()` rewrites that one error to name the
-  switch and the Docker-Desktop-VM-vs-your-machine distinction. Do not let it degrade to a raw
-  bollard string.
+  module has to back it.
+- **A missing device fails at `start`, not `create` — verified against Docker 29.7.** `docker
+  create --device /dev/does-not-exist` succeeds and prints an id; runc resolves the device (and
+  validates sysctls) only when it builds the container. So the guard belongs on the start path:
+  `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.
+- **`wg-quick` full tunnels need `xt_CONNMARK` from the host kernel**, which WSL2 does not have and
+  a container cannot load; `Recommends: nftables | iptables` is also stripped by
+  `--no-install-recommends`, so `nftables` is baked explicitly. See the Dockerfile comment — the
+  short version is that shipping the backend fixes native Linux and Docker Desktop for Mac, nothing
+  fixes Docker Desktop for Windows, and adding the routes directly with `ip route` sidesteps it on
+  all three.
 
 ### Container Lifecycle
 

HOW-TO-USE.md

@@ -477,21 +477,61 @@ 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, OpenVPN or Tailscale 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.
+The `ip`, `wg` and `nft` 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. Installing them by hand with `sudo apt install wireguard-tools` 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.
+
+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
+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:
 
-- `NET_ADMIN` applies to the container's **own** network namespace. It confers no authority over
-  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.
+- Tailscale is the exception: in its `--tun=userspace-networking` mode it needs neither the
+  capability nor the device, so leave this off if that is all you want.
+
+- `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 fails to create with an
-  error naming `/dev/net/tun` and pointing back at this setting.
+  the Linux VM, not your own machine. If it is missing, the container is created but fails to
+  **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.
+- **`wg-quick` cannot bring up a full tunnel on Docker Desktop for Windows.** Its `Table=auto` mode
+  routes by firewall mark and needs `xt_CONNMARK` from the host kernel, which WSL2's does not have
+  and a container cannot load. Split tunnels (a specific `AllowedIPs`) work fine, as does adding
+  the routes yourself with `ip route`. Native Linux and Docker Desktop for Mac are unaffected.
 
 > 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.

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

@@ -830,8 +830,16 @@ type VpnHostConfigParts = (
 ///   its handshake packets are dropped by reverse-path filtering. Harmless for
 ///   OpenVPN-based clients, so it is set unconditionally with the rest.
 ///
-/// This is namespaced to the container's own network stack: `NET_ADMIN` confers
-/// no authority over the host's interfaces or over any other container.
+/// What it costs, stated accurately: Docker does not enable user-namespace
+/// remapping by default, so this is a real `CAP_NET_ADMIN` in the *initial*
+/// 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.
 fn vpn_host_config(enabled: bool) -> VpnHostConfigParts {
     if !enabled {
         return (None, None, None);
@@ -857,31 +865,42 @@ fn vpn_host_config(enabled: bool) -> VpnHostConfigParts {
 
 /// Turn the daemon's device-passthrough failure into an explanation.
 ///
-/// Requesting `/dev/net/tun` fails at *creation* when the host kernel has no
-/// `tun` module — and the raw bollard error names a path the user will look for
-/// on the wrong machine, since with Docker Desktop the relevant host is the
-/// Linux VM rather than their own. Left unmapped this surfaces as a project
-/// that simply refuses to start, with nothing pointing back at the switch that
-/// caused it.
-fn explain_create_failure(err: &str, vpn_enabled: bool) -> String {
-    let device_missing = vpn_enabled
-        && err.contains(TUN_DEVICE)
+/// **This fires on `start`, not `create`.** Verified against Docker 29.7:
+/// `docker create --device /dev/does-not-exist` succeeds and prints an id; the
+/// device is only resolved when runc builds the container, so the failure lands
+/// on the *next* call. Sysctls validate at the same point. Anything that
+/// inspects only the create path will never see it — which is why both paths
+/// route through here and the tests exercise the start-side string.
+///
+/// Unmapped, this reads as `Failed to start container: Docker responded with
+/// status code 500: error gathering device information while adding custom
+/// 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 create container: the Docker host has no {} device, which \
+            "Failed to {} 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: {}",
-            TUN_DEVICE, err
+            action, TUN_DEVICE, err
         );
     }
 
-    format!("Failed to create container: {}", err)
+    format!("Failed to {} container: {}", action, err)
 }
 
 pub async fn create_container(
@@ -1574,7 +1593,7 @@ pub async fn create_container(
     let response = docker
         .create_container(Some(options), config)
         .await
-        .map_err(|e| explain_create_failure(&e.to_string(), project.vpn_support_enabled))?;
+        .map_err(|e| explain_container_failure("create", &e.to_string()))?;
 
     Ok(response.id)
 }
@@ -1584,7 +1603,7 @@ pub async fn start_container(container_id: &str) -> Result<(), String> {
     docker
         .start_container(container_id, None::<StartContainerOptions<String>>)
         .await
-        .map_err(|e| format!("Failed to start container: {}", e))
+        .map_err(|e| explain_container_failure("start", &e.to_string()))
 }
 
 pub async fn stop_container(container_id: &str) -> Result<(), String> {
@@ -2770,31 +2789,53 @@ mod tests {
         assert_eq!(cap_add.unwrap(), vec!["NET_ADMIN"]);
     }
 
+    /// 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_rather_than_echoed() {
-        let raw = "error gathering device information while adding custom device \
-                   \"/dev/net/tun\": no such file or directory";
-        let msg = explain_create_failure(raw, true);
+    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(raw), "should keep the original error: {}", msg);
+        assert!(msg.contains("Config → Runtime"), "should say where to fix it: {}", 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() {
-        // Including a tun error on a project that never asked for VPN support —
-        // that came from somewhere else and must not be misattributed.
-        let name_clash = "Conflict. The container name \"/triple-c-x\" is already in use";
-        assert_eq!(
-            explain_create_failure(name_clash, true),
-            format!("Failed to create container: {}", name_clash)
-        );
-
-        let tun_err = "no such file or directory: /dev/net/tun";
-        assert_eq!(
-            explain_create_failure(tun_err, false),
-            format!("Failed to create container: {}", tun_err)
-        );
+        for (action, err) in [
+            ("create", "Conflict. The container name \"/triple-c-x\" is already in use"),
+            ("start", "Docker responded with status code 404: No such container"),
+            ("start", "error gathering device information while adding custom device \"/dev/dri/card0\""),
+        ] {
+            assert_eq!(
+                explain_container_failure(action, err),
+                format!("Failed to {} container: {}", action, err),
+                "{} should pass through untouched",
+                err
+            );
+        }
     }
 
     #[test]

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

@@ -135,6 +135,7 @@ 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 support (WireGuard tools)"),
 ];
 
 /// Headroom demanded on Docker's storage backend on top of the measured

app/src-tauri/src/models/project.rs

@@ -148,13 +148,14 @@ 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, Tailscale) installs and runs but its connection attempt hangs
-    /// until it times out, because it cannot create the tunnel interface or
-    /// touch the routing table.
+    /// OpenVPN) installs and runs but its connection attempt hangs until it
+    /// times out, because it cannot create the tunnel interface or touch the
+    /// routing table.
     ///
     /// Off by default and deliberately opt-in: `NET_ADMIN` lets anything in the
-    /// container reconfigure its own network stack, which is a meaningful step
-    /// out of the default sandbox. Unlike `auth_bridge_enabled` this *is*
+    /// container reconfigure its own network stack, which reaches further than
+    /// it sounds — see `vpn_host_config` for what it does and does not confer.
+    /// 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.

app/src/components/projects/home/config/RuntimeSection.test.tsx

@@ -0,0 +1,94 @@
+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();
+  });
+});

app/src/components/projects/home/config/RuntimeSection.tsx

@@ -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, 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."
+          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."
           control={
             <Toggle
               label="VPN support"

container/Dockerfile

@@ -34,6 +34,9 @@ RUN for i in 1 2 3 4 5; do \
     cron \
     bubblewrap \
     socat \
+    iproute2 \
+    wireguard-tools \
+    nftables \
     && rm -rf /var/lib/apt/lists/*
 
 # `libnss3-tools` above provides `certutil`. Chrome/Chromium read neither
@@ -42,6 +45,56 @@ 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 `nftables` 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*, not a bare ubuntu:24.04 — the base
+# already ships libelf1t64, so measuring on bare ubuntu over-counts by ~209 kB:
+# +9 packages, 5,614 kB on amd64 (4,153 kB of that is iproute2+wireguard-tools,
+# 1,461 kB is nftables). The same set on arm64 is 7,422 kB, measured against
+# ubuntu:24.04 since the arm64 base is not cached here.
+#
+# ## Why `nftables` specifically
+#
+# `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 without one:
+#
+#     [#] iptables-restore -n
+#     /usr/bin/wg-quick: line 32: iptables-restore: command not found
+#     wg-quick EXIT=127        (interface rolled back, split tunnels unaffected)
+#
+# `nftables` rather than `iptables` because `wg-quick` prefers it (`if type -p
+# nft`, so with both installed iptables is dead weight), it is the first
+# alternative in the package's own Recommends, and it is roughly half the size.
+#
+# This does NOT make `wg-quick`'s full-tunnel mode work everywhere. `Table=auto`
+# routes by fwmark and needs connection-mark tracking from the *host* kernel:
+#
+#     Warning: Extension CONNMARK revision 0 not supported, missing kernel module?
+#
+# WSL2's kernel has no `xt_CONNMARK` and containers have no /lib/modules to load
+# one from, so on Docker Desktop for Windows `wg-quick up` on a full tunnel fails
+# regardless of what is installed here. Native Linux and Docker Desktop for Mac
+# have it. Shipping the backend is what makes the difference on those two;
+# nothing shipped here can make the difference on WSL2, where the way out is to
+# add the routes with `ip route` instead of going through `wg-quick` at all.
+#
+# `iptables` is deliberately still NOT here: with `nftables` present `wg-quick`
+# never reaches for it, so it would add size and firewall surface for nothing.
+
 # 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