Skip to content

jackson2w/claude-code-skills / docker-vpn-killswitch-lxc

docker-vpn-killswitch-lxc

Unverified

Route only some Docker containers (downloaders such as yt-dlp, MeTube, Pinchflat) out through a commercial WireGuard VPN (ProtonVPN, Mullvad, etc.) from inside an unprivileged Proxmox LXC, with a two-layer kill switch so they can never fall back to the ISP: WireGuard `Table = off`, a dedicated Docker bridge with a fixed name, source-based ip rules into a routing table whose only permanent route is `unreachable`, and an nftables forward-hook drop in its own table. The rest of the LXC (Tailscale, Jellyfin, SMB, apt) stays on the LAN. Covers sanitising the provider's .conf, unit ordering, DNS, Tailscale's ip rules, and the two drills that prove each layer works alone. Trigger phrases include "VPN kill switch", "route docker through wireguard", "containers only through the VPN", "ProtonVPN for the downloaders", "no ISP fallback", "Table = off", "policy routing for a docker network", "split tunnel docker", "gluetun alternative", "wg-quick in an LXC".

VPN-only egress for selected Docker containers in an LXC

Built 2026-10-23 for the offline media server (media, CT 143, homelab-ansible playbooks/media-install.yml). Will wanted the downloaders' traffic hidden from the ISP without TorBox/debrid. The LXC itself had to stay on the LAN and tailnet: Jellyfin is served over Tailscale Serve, SMB is tailnet-only, and apt and Tailscale must not depend on a third-party VPN.

Why not gluetun or wg-quick's default routing:

  • Plain wg-quick installs a default route plus fwmark rules for everything in the namespace. That would send Tailscale, apt and Jellyfin through Proton too.
  • gluetun works by putting containers into its network namespace with network_mode: service:gluetun, which couples every downloader's lifecycle and published ports to the VPN container's.

The host-level design below keeps each container on an ordinary bridge. The kill switch lives in kernel routing and nftables, where it can be drilled and audited.

Design

  1. A dedicated Docker network with a fixed bridge name and subnet. Only containers attached to it are routed through the tunnel.

    networks:
      dl:
        driver: bridge
        driver_opts: { com.docker.network.bridge.name: br-dl }
        ipam: { config: [ { subnet: 172.30.0.0/24 } ] }
    

    Publish their web UIs on 127.0.0.1:<port> only and front them with Tailscale Serve. Replies to the host go back over br-dl into the host itself, never through the forward hook, so the UIs keep working while the tunnel is down.

  2. Source-based policy routing into a table that starts out unreachable. These come from a oneshot unit (media-killswitch.service) ordered Before=docker.service wg-quick@wg-proton.service:

    ip rule add from 172.30.0.0/24 to 172.30.0.0/24 lookup main priority 99   # container ↔ container
    ip rule add from 172.30.0.0/24 lookup 51820 priority 100
    ip route replace unreachable default metric 4278198272 table 51820
    

    The unreachable route is permanent. While the tunnel is down, packets from the subnet get Network is unreachable; they never fall through to the main table's LAN default. Keep the priorities below 5210, where Tailscale's own fwmark rules start, so these rules always win. Wrap each ip rule add in ip rule show | grep -q ... ||, because duplicates stack up on every restart.

  3. WireGuard with Table = off, adding only the table-51820 default. Render the provider's .conf through a template that:

    • drops any DNS = line. Otherwise wg-quick calls resolvconf and rewrites the LXC's DNS.
    • drops any existing Table = line.
    • inserts, after [Interface]:
      Table = off
      PostUp = ip route replace default dev %i table 51820
      PreDown = ip route del default dev %i table 51820
      

    The tunnel's default route then has the lower metric, and on wg-quick down the unreachable route takes over again. Store the whole provider .conf as one secret (here Infisical PROTONVPN_WG_CONF) and render it with no_log: true and mode 0600. Skip the tunnel tasks cleanly while the secret is absent; until it exists the downloaders just have no route.

  4. An nftables forward-hook drop, in its own table. This layer catches routing mistakes, such as a lost ip rule or a hand-added route:

    table inet media_ks
    delete table inet media_ks
    table inet media_ks {
      chain forward {
        type filter hook forward priority filter - 1; policy accept;
        iifname "br-dl" oifname != { "wg-proton", "br-dl" } counter drop
      }
    }
    
    • The table / delete table / table {} sequence makes the file idempotent.
    • Never flush ruleset in this file: Docker's own rules live in the same nftables.
    • priority filter - 1 runs the drop before Docker's accept rules.
    • Docker's MASQUERADE already covers any non-bridge exit interface, so traffic leaving through wg-proton is NATed to the tunnel address with no extra rule.

LXC prerequisites

  • WireGuard is a kernel module, so it has to be loaded on the Proxmox host (lsmod | grep wireguard). Inside an unprivileged LXC, ip link add type wireguard then works with the container's own CAP_NET_ADMIN.
  • The /dev/net/tun passthrough (lxc.cgroup2.devices.allow: c 10:200 rwm plus the lxc.mount.entry) is needed for Tailscale in the same LXC, not for WireGuard.
  • features: nesting=1 is needed for Docker (and for Debian 13 systemd anyway).

DNS

Containers use Docker's embedded resolver (127.0.0.11), which forwards through the host's resolver, here Pi-hole, which forwards to Quad9 over DoT. DNS therefore does not go through the VPN, by design: Pi-hole filtering still applies and the ISP still sees no plaintext names. If a provider must also do DNS, set dns: on the containers to the provider's in-tunnel resolver (Proton: 10.2.0.1). That address is only reachable via table 51820, so name lookups also fail closed when the tunnel is down.

Drills: prove each layer on its own

Run these from inside a container on the dl network (docker exec <c> curl -sS -m 8 https://ifconfig.me). Each drill needs a control: the LXC host itself must still reach the internet, or the drill proves nothing (see the forced-outage-drill skill).

  1. Exit IP. The container shows the VPN exit, and the host shows the ISP address. On 2026-10-23: 149.88.100.198 (Proton, Dallas) vs. 66.169.192.156.
  2. Route layer. Run wg-quick down wg-proton, then the container gets Network is unreachable while the host's control request still succeeds. Bring the tunnel back up.
  3. nft layer alone. With the tunnel down, temporarily delete the priority-100 ip rule, so routing would now leak via the LAN. The request must still fail, and nft list chain inet media_ks forward must show the drop counter rising (6 packets on 2026-10-23). Re-add the rule by restarting media-killswitch.service, and check that ip rule matches the baseline.
  4. Site check. With the tunnel up, the actual target (e.g. YouTube) returns 200 through it. Some VPN exits are blocked by sites, so pick another server if not.

Re-run the playbook afterwards and expect changed=0. Compare ip rule and the table-51820 routes against the baseline, so no drill state lingers.

Monitoring: the kill switch fails silently

Failing closed means a dead tunnel looks like nothing at all: downloads stop and no unit fails. wg-quick@ is a oneshot that stays "active (exited)" whatever the peer does, and handshake age is no use either, because WireGuard stops handshaking when idle. Probe the egress itself from a container on the dl network instead, on a schedule that alerts:

docker exec pinchflat curl -sS -m 10 https://1.1.1.1/cdn-cgi/trace | sed -n 's/^ip=//p'

Fail if nothing comes back (tunnel down), or if the result equals the host's own trace IP (a leak). Using the IP avoids DNS. Here this is media_vpn_egress in the homelab sweep's service category (daily drift check), drilled 2026-10-24 by stopping wg-quick@wg-proton.

Also check that any yt-dlp bundled in an image is fresh. MeTube's sat 63 days old after the build; YouTube breaks old yt-dlp within weeks. Pinchflat updates its own.

Gotchas

  • Rules added by hand don't survive a restart. Everything has to come from the unit, which must run before docker and wg-quick at boot.
  • Recreating the Docker network can change the bridge name unless com.docker.network.bridge.name is pinned. The nft rule matches on br-dl by name.
  • Changing the subnet means changing it in three places: the ip rules, the compose IPAM and any monitoring that greps for it.
  • Tailscale Serve traffic bypasses nftables input rules (it arrives from the tailscaled process, not the tailscale0 interface; see the reference_tailscale_serve_bypasses_nftables memory). Restrict Serve ports with ACLs or app auth, not the nft input chain. The iifname != { lo, tailscale0 } drops here only keep SMB and discovery off the LAN.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexVerifiedInstall