Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
  shadow-testandClaude Opus 5
|
92d64cf252 | ||
|
shadow-testandClaude Opus 5
|
ab2c75d0b2 |
@@ -203,7 +203,8 @@ docker exec stdout → tokio task → emit("terminal-output-{sessionId}") → li
|
||||
### Container (`container/`)
|
||||
|
||||
- **`Dockerfile`** — Ubuntu 24.04 base with Claude Code, Node.js 22, Python 3.12, Rust, Docker CLI, git, gh, AWS CLI v2, ripgrep, pnpm, uv, ruff pre-installed, plus the shared
|
||||
libraries a browser links against (see below)
|
||||
libraries a browser links against (see below) and the VPN tooling the `vpn_support_enabled`
|
||||
toggle grants capability for (`iproute2`, `wireguard-tools`, `iptables`)
|
||||
- **Browser runtime libraries are baked in; browser *binaries* are not.** A layer runs
|
||||
`npx --yes playwright@latest install-deps chromium` as root, so Playwright names its own
|
||||
dependencies and the list cannot rot against Ubuntu 24.04's `t64` renames or a new Chromium
|
||||
@@ -316,17 +317,29 @@ container is created once by a very long function where a dropped capability is
|
||||
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 `/run`
|
||||
state persists through the snapshot and makes it look as though it did. Traffic silently reverts
|
||||
to the real address. Any future autostart or killswitch work starts here.
|
||||
- **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 existing projects, 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, 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.
|
||||
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.
|
||||
|
||||
### Container Lifecycle
|
||||
|
||||
|
||||
+44
-27
@@ -475,23 +475,21 @@ When enabled, the host Docker socket is mounted into the container so Claude Cod
|
||||
|
||||
When enabled, the container is given the three things a VPN client needs to build a tunnel:
|
||||
the `NET_ADMIN` capability, the `/dev/net/tun` device, and the `net.ipv4.conf.all.src_valid_mark`
|
||||
sysctl that WireGuard requires. The `ip` and `wg` commands are always present to use them. This is
|
||||
**off by default**.
|
||||
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
|
||||
them. If your project's container was created from an older base image it will not have them, and
|
||||
`wg` will simply not be found — **migrating the project onto the current base image** is what picks
|
||||
them up. `sudo apt install iproute2 wireguard-tools iptables` works in the meantime, but lives in
|
||||
the writable layer, so it is undone by a **Reset** and by a migration.
|
||||
|
||||
**This setting makes a tunnel possible; it does not make one.** Nothing is connected, no traffic is
|
||||
redirected, and no client is installed or started on your behalf. Enabling it and expecting the
|
||||
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 —
|
||||
installing a client and routing traffic into it remains yours to do.
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
@@ -511,20 +509,38 @@ Things worth knowing:
|
||||
- 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. Files under `/run` may
|
||||
persist via the snapshot and make it *look* like the tunnel is still configured, but after any
|
||||
stop/start, Reset or recreation 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.** Containers
|
||||
resolve through an address on the Docker network (`192.168.65.7` under Docker Desktop) that sits
|
||||
outside the container's own subnet, so 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. The
|
||||
symptom 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 use the VPN provider's own resolver for everything else. Note that
|
||||
a health check which fetches an IP literal such as `1.1.1.1` passes cleanly while this is broken —
|
||||
resolve a name instead.
|
||||
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.
|
||||
@@ -1284,6 +1300,7 @@ The sandbox container (Ubuntu 24.04) comes pre-installed with:
|
||||
| ruff | Latest | Python linter/formatter |
|
||||
| Rust | Stable | Rust development (via rustup) |
|
||||
| Docker CLI | Latest | Container management (when spawning is enabled) |
|
||||
| iproute2, WireGuard tools, iptables | Latest | Building a tunnel (when VPN Support is enabled) |
|
||||
| git | Latest | Version control |
|
||||
| GitHub CLI (gh) | Latest | GitHub integration |
|
||||
| AWS CLI | v2 | AWS services and Bedrock |
|
||||
|
||||
@@ -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
|
||||
@@ -1276,15 +1275,6 @@ pub async fn create_container(
|
||||
env_vars.push("MISSION_CONTROL_ENABLED=1".to_string());
|
||||
}
|
||||
|
||||
// Drives the pia-vpn skill install in entrypoint.sh. Sent as 0 rather than
|
||||
// omitted when off, because ~/.claude is a persisted volume: entrypoint has
|
||||
// to be told to *remove* a skill left there by an earlier run with the
|
||||
// toggle on, and an absent variable cannot say that.
|
||||
env_vars.push(format!(
|
||||
"VPN_SUPPORT_ENABLED={}",
|
||||
u8::from(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!(
|
||||
@@ -2799,23 +2789,6 @@ mod tests {
|
||||
assert_eq!(cap_add.unwrap(), vec!["NET_ADMIN"]);
|
||||
}
|
||||
|
||||
#[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
|
||||
|
||||
@@ -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 tooling (WireGuard, for the VPN Support toggle)"),
|
||||
];
|
||||
|
||||
/// Headroom demanded on Docker's storage backend on top of the measured
|
||||
|
||||
+63
-18
@@ -36,6 +36,7 @@ RUN for i in 1 2 3 4 5; do \
|
||||
socat \
|
||||
iproute2 \
|
||||
wireguard-tools \
|
||||
iptables \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# `libnss3-tools` above provides `certutil`. Chrome/Chromium read neither
|
||||
@@ -44,22 +45,75 @@ 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` and `wireguard-tools` 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.
|
||||
# `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. Together they are ~4.3 MB including dependencies.
|
||||
# never started.
|
||||
#
|
||||
# `iptables` is deliberately NOT here. The only thing that wants it is a desktop
|
||||
# VPN client's killswitch, and those clients need a GUI that a container has no
|
||||
# way to give them; leaving it out keeps the reach of CAP_NET_ADMIN smaller.
|
||||
# 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 \
|
||||
@@ -333,15 +387,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
|
||||
RUN chmod +x /opt/triple-c-skills/*/*.sh
|
||||
|
||||
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,35 +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.
|
||||
install_feature_skill() {
|
||||
_name=$1
|
||||
_enabled=$2
|
||||
_dest="/home/claude/.claude/skills/$_name"
|
||||
if [ "$_enabled" = "1" ]; then
|
||||
[ -d "/opt/triple-c-skills/$_name" ] || return 0
|
||||
mkdir -p /home/claude/.claude/skills
|
||||
rm -rf "$_dest"
|
||||
cp -r "/opt/triple-c-skills/$_name" "$_dest"
|
||||
chown -R claude:claude "$_dest"
|
||||
echo "entrypoint: $_name skill installed to ~/.claude/skills/"
|
||||
elif [ -d "$_dest" ]; then
|
||||
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,175 +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.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
Set `PIA_CREDS` to use a different path. 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.
|
||||
|
||||
## 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 and removes exactly the routes
|
||||
that were added, in reverse order, then 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.
|
||||
|
||||
## What this deliberately does not do
|
||||
|
||||
- **No killswitch.** Blocking non-tunnel egress needs `iptables`, which is not
|
||||
in the image, and would cut Claude Code's API traffic whenever the tunnel is
|
||||
down. If the user needs guaranteed egress rather than convenient egress, say
|
||||
so plainly rather than improvising one — it is a real design decision.
|
||||
- **No autostart.** There is no service manager in the container and Triple-C
|
||||
has no start hook, so nothing can re-establish the tunnel automatically.
|
||||
- **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.
|
||||
@@ -1,201 +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.
|
||||
#
|
||||
# PIA_CREDS credentials file, two lines: username, then password
|
||||
# (default ~/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
|
||||
|
||||
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; }
|
||||
|
||||
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.
|
||||
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
|
||||
[ -e /dev/net/tun ] || \
|
||||
die "/dev/net/tun is missing." \
|
||||
"Same fix: turn on \"VPN support\" in Config -> Runtime. If it is" \
|
||||
"already on, the Docker host's kernel is missing the tun module."
|
||||
command -v wg >/dev/null || die "wireguard-tools is not installed."
|
||||
[ -r "$CREDS" ] || \
|
||||
die "no credentials at $CREDS." \
|
||||
"Two lines are expected: username, then password." \
|
||||
"Set PIA_CREDS to read them from somewhere else."
|
||||
}
|
||||
|
||||
# Record every route we add so teardown removes exactly those and nothing else.
|
||||
add_route() { ip route add $1 2>/dev/null && echo "$1" >> "$STATE/routes" || true; }
|
||||
|
||||
up() {
|
||||
preflight
|
||||
mkdir -p "$STATE"; cd "$STATE"
|
||||
[ -f ca.rsa.4096.crt ] || curl -sf -m 20 -o ca.rsa.4096.crt \
|
||||
https://raw.githubusercontent.com/pia-foss/manual-connections/master/ca.rsa.4096.crt \
|
||||
|| die "could not fetch PIA's CA certificate"
|
||||
|
||||
local u p tok srv sip scn priv pub resp ep gw dns
|
||||
u=$(sed -n 1p "$CREDS"); p=$(sed -n 2p "$CREDS")
|
||||
tok=$(curl -sf -m 25 -u "$u:$p" \
|
||||
https://www.privateinternetaccess.com/gtoken/generateToken | jq -r .token)
|
||||
[ -n "$tok" ] && [ "$tok" != null ] || die "PIA authentication failed - check $CREDS"
|
||||
|
||||
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"
|
||||
|
||||
priv=$(wg genkey); pub=$(echo "$priv" | wg pubkey)
|
||||
printf '%s' "$priv" > wg.priv; chmod 600 wg.priv
|
||||
|
||||
# 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=$(curl -sf -m 25 -G --connect-to "$scn::$sip:" --cacert ca.rsa.4096.crt \
|
||||
--data-urlencode "pt=$tok" --data-urlencode "pubkey=$pub" \
|
||||
"https://$scn:1337/addKey")
|
||||
[ "$(echo "$resp" | jq -r .status)" = OK ] || die "key registration failed: $resp"
|
||||
|
||||
: > "$STATE/routes"
|
||||
ip link del "$IFACE" 2>/dev/null || true
|
||||
ip link add "$IFACE" type wireguard
|
||||
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
|
||||
ip addr add "$(echo "$resp" | jq -r .peer_ip)/32" dev "$IFACE"
|
||||
ip link set "$IFACE" up
|
||||
|
||||
if [ "${1:-}" = "--full" ]; then
|
||||
# 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.
|
||||
ep=$(echo "$resp" | jq -r .server_ip)
|
||||
gw=$(ip route show default | awk '{print $3; exit}')
|
||||
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 resolver lives inside 10/8, so pin it back through the tunnel with a
|
||||
# /32 -- longer still, so it beats the 10.0.0.0/8 exclusion just added.
|
||||
# Using PIA's resolver rather than the container's keeps DNS from leaking,
|
||||
# and the container's own resolver is unreachable from inside the tunnel.
|
||||
dns=$(echo "$resp" | jq -r '.dns_servers[]? // empty' | head -2)
|
||||
if [ -n "$dns" ]; then
|
||||
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
|
||||
else
|
||||
echo "pia-wg: warning - PIA returned no DNS servers; leaving resolv.conf alone" >&2
|
||||
fi
|
||||
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
|
||||
|
||||
sleep 2
|
||||
status
|
||||
}
|
||||
|
||||
down() {
|
||||
[ "$(id -u)" = 0 ] || die "run with sudo"
|
||||
if [ -f "$STATE/resolv.conf.bak" ]; then
|
||||
cat "$STATE/resolv.conf.bak" > /etc/resolv.conf
|
||||
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
|
||||
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 "$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,20p' "$0" | sed 's/^# \{0,1\}//'; exit 1 ;;
|
||||
esac
|
||||
Reference in New Issue
Block a user