Private browser routing. Ghost-style protection. Your endpoint, your traffic path.
A privacy-focused Chromium proxy client built from scratch as a Manifest V3 extension. Route browser traffic through an endpoint you control, verify the route live, and reduce browser-level location leakage.
Ghost Web VPN follows one principle: the browser should use an endpoint you control, not a bundled third-party proxy fleet.
The extension configures Chromium's proxy stack, checks whether the route actually works, remembers the last endpoint, and restores it after browser restarts.
Important: Ghost Web VPN is a browser proxy client, not a standalone network-level VPN. A system-wide VPN requires a separately operated gateway such as WireGuard or OpenVPN.
| Area | Ghost Web VPN |
|---|---|
| 🔌 Connection | One-click connect / disconnect |
| ✅ Verification | Live connectivity check through the proxy |
| 🔁 Recovery | Auto-reconnect and keep-alive |
| 🌍 Location | Region presets + connection-based detection |
| 🕒 Browser privacy | Geolocation, timezone, Date, Intl and permission surfaces |
| 🌐 Protocols | HTTP, HTTPS, SOCKS4 and SOCKS5 |
| 🔐 HTTP(S) auth | onAuthRequired authentication |
| 💾 Storage | Persistent local extension configuration |
| 🧩 Platform | Chromium / Chrome Manifest V3 |
| 🖥️ Endpoint | Self-hosted and user-controlled |
| 🚫 Bundled servers | None |
Use a Linux machine you already control: home PC, mini-PC, Raspberry Pi, or always-on server. The included setup uses Tailscale's free tier and a SOCKS5 proxy bound to the private Tailscale address.
cd server/free-self-hosted
sudo bash setup-free-endpoint.shThe installer prints the settings to enter in Ghost Web VPN:
Protocol: socks5
Host: 100.x.y.z
Port: 1080
Username: blank
Password: blank
Press Connect. Ghost verifies the route instead of assuming that the proxy configuration succeeded.
The repository also contains deployment tooling for free open-source VPS infrastructure. FOSSVPS is the primary free VPS target for the project; the intended deployment flow is SSH details → bootstrap → configured endpoint.
┌───────────────────────┐
│ Chromium + Ghost │
│ Web VPN Extension │
└───────────┬───────────┘
│ chrome.proxy
▼
┌───────────────────────┐
│ Your proxy endpoint │
│ SOCKS4 / SOCKS5 / │
│ HTTP / HTTPS │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Endpoint Internet │
│ connection / public IP│
└───────────────────────┘
A proxy changes the network path, but browsers can expose additional location signals. Ghost includes a document_start content script for browser-level location protection.
It can align:
- Geolocation API results
- Browser timezone
Datetimezone behaviourIntllocale/timezone surfaces- Relevant permission responses
- Best-effort WebRTC hardening while connected
Choose a region preset or detect a region from the active connection.
Chrome does not provide SOCKS5 proxy authentication through the extension proxy API, so SOCKS4/SOCKS5 credentials remain blank.
For the included free endpoint, the proxy is bound to the machine's Tailscale address, not a public interface. Do not expose an unauthenticated SOCKS5 listener on 0.0.0.0.
HTTP(S) authentication remains supported through onAuthRequired, with credentials kept in extension storage rather than source control.
- Clone this repository.
- Open
chrome://extensionsin Chrome or Chromium. - Enable Developer mode.
- Select Load unpacked.
- Choose the repository directory.
- Enter the protocol, host and port for an endpoint you control.
- Press Connect.
- Confirm the live connectivity check reports success.
GitHub Actions packages the extension as ghost-web-vpn.zip.
Every push to main and every pull request runs the validation workflow. The CI gate checks:
- Manifest JSON validity
- JavaScript syntax for all extension scripts
- Required extension/server files
- Manifest V3 permissions and structure
- Docker Compose configuration
- Setup-script shell hygiene when ShellCheck is available
- Private-key material accidentally committed
- Creation of the distributable extension ZIP
Build gate: validate → package → artifact upload.
ghost-web-vpn/
├── background.js # Proxy lifecycle, reconnect and auth
├── popup.html # Extension UI
├── popup.css # Ghost dark UI styling
├── popup.js # Controls and connectivity checks
├── presets.js # Region presets
├── spoof.js # Browser location/privacy layer
├── manifest.json # Chrome Manifest V3 definition
├── icon.svg # Ghost brand icon
├── icons/ # Extension PNG icons
├── QUICKSTART.md # From-zero setup guide
├── server/
│ ├── README.md # Server/deployment documentation
│ ├── docker-compose.yml # Endpoint stack
│ └── free-self-hosted/ # Tailscale endpoint
└── .github/workflows/ci.yml # Automated validation + packaging
Ghost does not bundle a commercial proxy network. You choose and operate the endpoint.
Connection state is verified instead of assuming that applying a Chromium proxy configuration means traffic is working.
Private keys, passwords and long-lived secrets belong in authenticated configuration or secret storage — never source control.
The extension stays focused on browser routing, verification and browser-level privacy controls.
- Not a system-wide VPN by itself.
- The endpoint must be online.
- Destination websites see the endpoint's public IP.
- Home/self-hosted performance depends on upload bandwidth and ISP.
- SOCKS5 authentication is unavailable through Chromium's extension API.
- Location spoofing reduces browser-level leakage but cannot guarantee anonymity against every fingerprinting technique.
- Manifest V3 Chromium extension
- HTTP / HTTPS / SOCKS4 / SOCKS5
- Live connection verification
- Persistent endpoint configuration
- Auto-reconnect / keep-alive
- Region presets and connection detection
- Browser location protection
- Free Tailscale self-hosted endpoint
- Automated CI validation and ZIP packaging
- FOSSVPS deployment target
- Hardened production provisioning
- Expanded endpoint health diagnostics
- Additional Chromium privacy hardening
- Quick Start — from clone to working endpoint
- Free self-hosted endpoint — Tailscale + SOCKS5
- Server documentation — endpoint and deployment options
- CI workflow — validation and packaging
Issues, improvements and pull requests are welcome. Keep changes privacy-focused, avoid hard-coded credentials, and keep CI green.
Questions, feedback or support requests: ghostweb@ghostbin.cfd
Ghost Web VPN · private routing for the browser you control 👻