tempVPN

tempVPN is a Codex skill that buys a temporary WireGuard VPN session with a Tempo MPP payment, connects the local machine, tracks connected-time usage, and verifies the public IP.

Important

Linux uses the Rust CLI with WireGuard command-line tools. macOS uses the Swift tempvpnctl plus an invisible native host and Packet Tunnel extension backed by WireGuardKit. Windows is not supported.

How it works

Node daemons --authenticated state/leases--> durable coordinator and catalogs
Registry merges /nodes and owns fixed MPP challenges plus lifecycle state
Clients latency-rank healthy nodes, then pay POST /sessions at the registry
Linux vpn-client or macOS tempvpnctl activates portable balance by node_id

Only the WireGuard public key is sent when activating the paid balance. The private key remains local, and the server removes the peer automatically when connected time is exhausted or the grace deadline passes.

The three important parts

1. The Codex skill (tempvpn/SKILL.md)

   Turns a request such as “connect for 30 minutes” into the correct workflow. It tells the agent how to pay, connect, verify the exit IP, and disconnect without exposing private keys or using server admin credentials.

2. The platform clients (vpn-client on Linux; native headless TempVPN.app/tempvpnctl on macOS)

   Select a healthy node, import the paid response, retain private keys locally, start the tunnel, heartbeat usage, and pause unused time on disconnect.

3. The VPN node, registry, and coordinator

   The registry validates fixed Tempo MPP payments and the coordinator stores portable balances durably. Nodes advertise live capacity, activate temporary WireGuard peers after authenticated registry routing, reconcile peer state, and continue to own the separate node-affine Session v2 streaming product.

See tempvpn/README.md for implementation and server details.

Prerequisites

• A configured registry URL — distributed to both platform clients.
• Codex — discovers and loads the skill for natural-language operation.
• WireGuard tools and Rust/Cargo — required for the Linux CLI.
• Xcode, Go, WireGuardKit, and Apple signing — required for the native headless macOS client. It has no graphical interface.
• Node.js/npm and mppx — handles the Tempo MPP payment.
• A funded MPPX account named main — used for VPN payments and stored in macOS Keychain.

Install the command-line dependencies:

brew install wireguard-tools
npm install -g mppx

Install Rust from rustup.rs. Follow the MPP agent quickstart to create and fund the main account:

mppx account create --account main
mppx account view --account main

Create or replace an MPPX account only as an explicit setup action in a trusted terminal. Never share or commit its private key.

Install and build

git clone https://github.com/protocolwhisper/tempVPN.git
cd tempVPN/tempvpn
cargo build -p vpn-client-cli
./clients/macos/build-macos-products.sh

Before signing, the macOS build is for compilation verification only. Once the app, Packet Tunnel extension, and CLI are signed with the same Apple team, the installer places the invisible host in /Applications and tempvpnctl in /usr/local/bin.

Load the skill into Codex

Ask Codex to install it:

$skill-installer Install the skill from https://github.com/protocolwhisper/tempVPN/tree/main/tempvpn/agent

The skill records that same canonical bundle URL and the raw SKILL.md URL in its own instructions. To check for updates later, ask Codex to compare the installed tempvpn bundle with that canonical source and reinstall it after showing you the changes. The entrypoint and verification scripts must always come from the same repository commit.

Alternatively, link a local clone into the user skill directory:

mkdir -p "$HOME/.agents/skills"
ln -s "/absolute/path/to/tempVPN/tempvpn" "$HOME/.agents/skills/tempvpn"

Codex normally detects the skill automatically. Restart Codex if it does not appear in /skills. These locations follow the official Codex skills documentation.

Invoke the skill explicitly:

$tempvpn Buy 30 minutes of VPN access, connect, and verify the public IP.

You can also say: Load tempvpn and connect for 30 minutes.

Current scope

Linux and macOS are supported. Never share private keys, daemon admin tokens, or registry-write tokens with the client or agent.