From bf9d1fca56a54977feb12b6348cd717ed8dd8f9e Mon Sep 17 00:00:00 2001 From: Jeremie Fraeys Date: Sat, 28 Mar 2026 18:33:46 -0400 Subject: [PATCH] docs(wireguard): add WireGuard VPN documentation Add comprehensive WireGuard documentation: - docs/wireguard/index.md: main WireGuard documentation - docs/wireguard/opencode-studio.md: opencode-studio VPN setup - docs/wireguard/vpn-setup.md: general VPN setup guide - docs/wireguard/wg.md: wg command reference --- docs/wireguard/index.md | 46 ++++++++++++ docs/wireguard/opencode-studio.md | 112 ++++++++++++++++++++++++++++++ docs/wireguard/vpn-setup.md | 76 ++++++++++++++++++++ docs/wireguard/wg.md | 65 +++++++++++++++++ 4 files changed, 299 insertions(+) create mode 100644 docs/wireguard/index.md create mode 100644 docs/wireguard/opencode-studio.md create mode 100644 docs/wireguard/vpn-setup.md create mode 100644 docs/wireguard/wg.md diff --git a/docs/wireguard/index.md b/docs/wireguard/index.md new file mode 100644 index 0000000..b2ea9c8 --- /dev/null +++ b/docs/wireguard/index.md @@ -0,0 +1,46 @@ +--- +layout: default +title: WireGuard VPN +nav_order: 2 +--- + +# WireGuard VPN + +Client-side WireGuard management tools for connecting to a VPN. + +## Setup + +Use `vpn-setup` to configure new machines: + +```bash +vpn-setup up my-mac --server 1.2.3.4 +``` + +## Scripts + +| Script | Purpose | +|--------|---------| +| `vpn-setup` | Configure new VPN clients | +| `wg` | Daily tunnel management (up/down/status) | +| `opencode-studio` | MLX workflow wrapper (SSH tunnel over VPN) | + +## Key Storage + +All keys are stored in **Bitwarden**: + +- Peer configs: `wireguard-peer-` (secure notes with fields) +- Server public key: included in peer config + +## Daily Use + +```bash +wg up +wg down +wg status +``` + +## See Also + +- [vpn-setup](vpn-setup.md) — Client configuration +- [wg](wg.md) — Daily tunnel management +- [opencode-studio](opencode-studio.md) — MLX workflow wrapper diff --git a/docs/wireguard/opencode-studio.md b/docs/wireguard/opencode-studio.md new file mode 100644 index 0000000..7533c04 --- /dev/null +++ b/docs/wireguard/opencode-studio.md @@ -0,0 +1,112 @@ +--- +layout: default +title: opencode-studio +parent: WireGuard VPN +--- + +# opencode-studio + +MLX workflow wrapper for server and client machines. + +## Overview + +This script manages the MLX LM server connection between a server (where MLX runs) and clients (which connect via SSH tunnel). It auto-detects the machine role based on hostname or can be forced with flags. + +**Flexible Connection**: Works over VPN, local network, or internet — just specify the server hostname. + +## Usage + +```bash +opencode-studio [OPTIONS] +``` + +## Commands + +| Command | Description | +|---------|-------------| +| `status` | Check if MLX server is running and show models | +| `up`, `start` | Start MLX server (local) or open SSH tunnel (remote) | +| `down`, `stop` | Stop MLX server (local) or close SSH tunnel (remote) | + +## Options + +| Option | Description | Default | +|--------|-------------|---------| +| `-p, --port ` | MLX port | 11434 | +| `-s, --server ` | Server hostname for SSH | studio | +| `--local` | Force local mode (start MLX server) | auto-detect | +| `--remote` | Force remote mode (SSH tunnel) | auto-detect | +| `-n, --dry-run` | Print actions without executing | - | +| `-v, --verbose` | Verbose output | - | +| `-h, --help` | Show help | - | + +## Role Detection + +The script auto-detects whether it's running on a server or client via hostname: + +- **Server role**: Hostnames matching `studio`, `mac-studio`, or `server` +- **Client role**: Hostnames matching `air`, `macbook-air`, or `laptop` + +Customize the `_is_server()` and `_is_client()` functions in the script for your hostnames. + +## Examples + +### Server (runs MLX) + +```bash +opencode-studio status +opencode-studio up +``` + +### Client (connects to server) + +```bash +# Auto-detect role, connect to default server +opencode-studio status +opencode-studio up + +# Connect to specific server +opencode-studio up --server myhost + +# Force client mode +opencode-studio up --server 192.168.1.10 --remote +``` + +### Cross-Platform Use + +Connect to any Linux/macOS server running MLX: + +```bash +# Over local network +opencode-studio up --server 192.168.1.10 + +# Over VPN +opencode-studio up --server 10.0.0.5 + +# Over internet (with proper SSH setup) +opencode-studio up --server mlx.example.com +``` + +## MLX API + +Once connected, the MLX API is available at `http://localhost:11434`: + +```bash +curl http://localhost:11434/v1/models +curl http://localhost:11434/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{"model": "mlx-model", "messages": [{"role": "user", "content": "Hello"}]}' +``` + +## Decoupled from VPN + +This script works independently of the WireGuard VPN. You can: +- Use it with VPN (recommended for security) +- Use it over local network +- Use it over the internet (with SSH key authentication) + +The `--server` flag accepts any hostname or IP address. + +## See Also + +- [WireGuard VPN index](index.md) diff --git a/docs/wireguard/vpn-setup.md b/docs/wireguard/vpn-setup.md new file mode 100644 index 0000000..58c68a3 --- /dev/null +++ b/docs/wireguard/vpn-setup.md @@ -0,0 +1,76 @@ +--- +layout: default +title: vpn-setup +parent: WireGuard VPN +--- + +# vpn-setup + +WireGuard client setup — one command to generate keys and configure the local machine. + +## Overview + +Replaces `gen-wireguard-keys` and `bootstrap-vpn`. Handles: + +- Generating WireGuard key pairs +- Storing in Bitwarden +- Writing local config +- Starting the tunnel + +**Note:** Daily tunnel management (up/down/status) is handled by `wg`. + +## Usage + +```bash +vpn-setup [options] +``` + +## Commands + +| Command | Description | +|---------|-------------| +| `up ` | Full setup: generate keys + bootstrap + start tunnel | +| `add ` | Generate keys and store in Bitwarden (no local setup) | +| `rm ` | Remove peer from Bitwarden | +| `list` | List all peers from Bitwarden | + +## Options + +| Option | Description | Default | +|--------|-------------|---------| +| `-s, --server ` | VPN server endpoint | required | +| `-p, --port ` | VPN server port | 51820 | +| `-S, --subnet ` | VPN subnet prefix | 10.0.0 | +| `-i, --interface ` | WireGuard interface | wg0 | +| `-n, --dry-run` | Print actions without executing | - | +| `-v, --verbose` | Verbose output | - | +| `-h, --help` | Show help | - | + +## Examples + +### New Machine Setup + +```bash +vpn-setup up my-mac --server 1.2.3.4 +``` + +### Managing Peers + +```bash +vpn-setup add new-laptop --server 1.2.3.4 +vpn-setup list +vpn-setup rm old-laptop +``` + +### Daily Use (after setup) + +```bash +wg down +wg up +wg status +``` + +## See Also + +- [WireGuard VPN index](index.md) +- [wg](wg.md) — Daily tunnel management diff --git a/docs/wireguard/wg.md b/docs/wireguard/wg.md new file mode 100644 index 0000000..1dd9a09 --- /dev/null +++ b/docs/wireguard/wg.md @@ -0,0 +1,65 @@ +--- +layout: default +title: wg +parent: WireGuard VPN +--- + +# wg + +Daily WireGuard tunnel management for macOS. + +## Usage + +```bash +wg [OPTIONS] +``` + +## Commands + +| Command | Description | +|---------|-------------| +| `up` | Bring interface up (idempotent) | +| `down` | Bring interface down (idempotent) | +| `restart` | Restart interface | +| `status` | Show connection status and peer info | +| `health` | Check tunnel health, auto-reconnect if dead | +| `peers` | Ping each peer and show reachability | +| `watch` | Health check loop every 30s | +| `autostart ` | Enable/disable auto-start on boot | + +## Options + +| Option | Description | Default | +|--------|-------------|---------| +| `-i, --interface ` | Interface name | `wg0` | +| `-n, --dry-run` | Print actions without executing | - | +| `-v, --verbose` | Verbose output | - | +| `-h, --help` | Show help | - | + +## Examples + +```bash +# Start the VPN +wg up + +# Check status +wg status + +# Health check with auto-reconnect +wg health + +# Monitor in watch mode +wg watch + +# Enable auto-start +wg autostart enable +``` + +## Auto-start on macOS + +Uses `launchd` to start the tunnel at boot. The script manages the launchd plist for you. + +## See Also + +- [bootstrap-vpn](bootstrap-vpn.md) — Initial VPN setup +- [WireGuard VPN index](index.md)