# wg-wrap: Transparent Userspace VPN Wrapper

`wg-wrap` allows you to run specific Linux applications over a WireGuard VPN without requiring root privileges or affecting your entire system's network configuration.

## 🚀 Quick Start

### 1. Install
Build the binary using the provided Makefile:
```bash
make
```

### 2. Setup a Profile
Import your WireGuard `.conf` file as a profile:
```bash
./wg-wrap profile import ~/my-vpn.conf home-vpn
```

### 3. Run an Application
Run any command wrapped in the VPN using the `run` subcommand:
```bash
./wg-wrap run --profile home-vpn -- curl https://ifconfig.me
```
*Only the `curl` command is routed through the VPN; your browser, SSH sessions, and other apps remain on your local network.*
*Only the `curl` command is routed through the VPN; your browser, SSH sessions, and other apps remain on your local network.*

---

## 🛠️ Feature Overview

### Process-Level Isolation
Unlike standard VPNs, `wg-wrap` provides complete network isolation per process. This means:
- **No Route Pollution**: Your host routing table remains untouched.
- **Rootless Operation**: Works without `sudo` using unprivileged user namespaces.
- **VPN Concurrency**: Run multiple different VPN profiles at the same time in different terminals.
- **Zero-Leak DNS**: Each process gets its own isolated DNS resolver, preventing leaks to your ISP.

### Profile Management
Manage your VPN configurations easily from the CLI:

| Command | Description |
| :--- | :--- |
| `run [options] -- <cmd>` | Run a command in the wrapped environment. |
| `profile list` | List all available VPN profiles. |
| `profile import <path> [name]` | Import a `.conf` file as a new profile. |
| `profile configure <name>` | Edit a profile's configuration in your default editor. |
| `profile delete <name>` | Remove a profile. |
| `profile stop <name>` | Force-stop an active tunnel session. |

### Diagnostics
Check your environment and troubleshoot issues using these subcommands:
- `healthcheck`: Run a comprehensive diagnostic to ensure your system supports rootless namespaces.
- `show-config`: View resolved paths and current isolation status.
- `test-ns`: Verify that you are correctly isolated in a network namespace.
- `test-args`: (For developers) Verify 8-bit clean argument passing.

---

## 📖 Usage Examples

**Run Firefox on a specific VPN:**
```bash
./wg-wrap run --profile privacy-vpn -- firefox
```

**Run a series of tests against a private VPC:**
```bash
./wg-wrap run --profile dev-vpc -- pytest tests/integration
```

**Connect to a home server and a work server simultaneously:**
```bash
# Terminal 1
./wg-wrap run --profile home-vpn -- ssh home-nas
# Terminal 2
./wg-wrap run --profile work-vpn -- ssh work-server
```

---

## 🏗️ Development

### Building from Source
`wg-wrap` requires `gcc` and `go` (1.23+). It uses an embedded C launcher to handle the rootless namespace transition, so you must use the Makefile:
```bash
make
```

### Testing
- **Unit & Integration Tests**: `make test`
- **Security Fuzzing**: `make fuzz` (tests argument integrity through the bootstrap loop).

### Development & Agentic Workflow
`wg-wrap` was built using an agentic development process. For a detailed analysis of the strategy, the timeline, and the synergy between the human architect and the AI agent, see [CASE_STUDY.md](./CASE_STUDY.md).

## License
This project is free and unencumbered software released into the public domain. See the [LICENSE](LICENSE) file for details.