wisp-vpn 0.1.0

██╗    ██╗██╗███████╗██████╗
██║    ██║██║██╔════╝██╔══██╗
██║ █╗ ██║██║███████╗██████╔╝
██║███╗██║██║╚════██║██╔═══╝
╚███╔███╔╝██║███████║██║
 ╚══╝╚══╝ ╚═╝╚══════╝╚═╝

A VPN for the sessions you actually need.

A monthly subscription bills you for every minute of the month so you can use thirty. Wisp spins up a WireGuard server in your own cloud account, connects you, and destroys it when you're done — measured: ~30 seconds to a working tunnel on your own VPS, ~2–3 minutes on a cloud provider (the VM boot is the slow part), and a typical session costs fractions of a cent on pay-as-you-go pricing.

Installation · Quick start · Documentation · Contributing

Why Wisp

Who it's for: developers who already have a cloud account (or a spare VPS) and use a VPN occasionally — a few sessions a month, not all day every day.

Who it's not for: if you need an anonymous exit IP, look elsewhere — Wisp's exit IP belongs to your cloud account or your VPS, which is the point.

• Designed so nothing outlives your session. The VM is destroyed on exit — q, Ctrl+C, closing the terminal — and an optional TTL watchdog tears down forgotten sessions. (The watchdog timer runs on your machine: if that machine is off or suspended when the TTL expires, the session survives until the next wisp gc — and wisp gc --destroy cleans up anything a crash left behind.)
• Nothing to clean up by hand. Orphan detection and wisp gc catch anything a crash left behind.
• Bring your own server. Already have a VPS? Skip the cloud entirely — Wisp configures WireGuard on it over SSH and cleans up after itself.
• No sudo at runtime. The privileged daemon owns the local WireGuard interface; the CLI/TUI never elevate after installation.

Features

How it works

   Wisp CLI/TUI ──Pulumi──▶ Cloud VM (AWS EC2 / OCI Compute / GCP + WireGuard)
        │  ▲                        │
        │  └──── Paramiko (SSH) ────┘   installs & configures the server
        ▼
   wisp daemon (privileged) ──wg-quick──▶ local WireGuard interface (wg0)

The client-side privileged daemon means the unprivileged CLI/TUI never needs sudo to bring the local tunnel up or down; it talks to the daemon over a group-restricted Unix socket (Linux) or Named Pipe (Windows) instead. The session guard arms before provisioning starts, so a crashed TUI still leaves a marker behind — the next run offers to clean it up, and the optional TTL watchdog handles it even if nobody reopens Wisp.

Install (from source)

Requirements: Python 3.14+ (if you install via uv, it manages Python for you — you never see this requirement), the Pulumi CLI, and WireGuard tools — both installed by the setup script.

# 0. Clone and enter the repo
git clone https://github.com/dosquisd/wisp.git && cd wisp

# 1. Install the CLI (isolated tool venv)
uv tool install .

# 2. Install the privileged local daemon (needs root/administrator)
sudo ./setup.sh            # Linux; or: sudo ./setup.sh --skip-pulumi
./setup.ps1                # Windows (self-elevates to administrator)

Then log out and back in (or newgrp wisp) so your wisp group membership takes effect. macOS is not supported yet (the daemon adapter is not implemented — see MacOSAdapter in daemon/adapter.py). A published PyPI package with a one-command installer is planned.

Quick start

# 1. Authenticate the Pulumi backend (the deployment state lives there)
pulumi login

# 2. Configure your cloud credentials (standard SDK chains — see docs)
aws configure               # or ~/.oci/config, or [gcp] in wisp.toml

# 3. Launch the TUI (or use the CLI directly)
wisp

# CLI equivalent — deploy, tunnel, destroy:
wisp deploy aws --region eu-west-1   # provisions VM + WireGuard, connects you
wisp destroy aws --region eu-west-1  # tears it all down

CLI cheat sheet

Supported providers

Note: as of this writing, Wisp ships with support for aws, oci, gcp, and vps. The provider layer is designed to be extensible — see ProviderEnum (src/wisp/providers/base.py) and PROVIDERS_MAP (src/wisp/providers/__init__.py), or the contributing guide to add your own.

Documentation

Full documentation lives in docs/:

Security

Keys are per-session RSA 4096 pairs, stored 0600 and removed on destroy. The daemon socket is group-restricted (root:wisp). Cloud credentials are never stored by Wisp — each provider uses its standard SDK chain (the only file Wisp ever touches is the optional [gcp].credentials_path, which you point at; Wisp reads it, it does not manage it). Read the full security model.

Contributing

PRs against main. The provider layer is the easiest entry point — see adding a cloud provider.

License

MIT — Copyright (c) 2026 Juan D. Perez