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
This commit is contained in:
Jeremie Fraeys
parent
17c6029d61
commit
bf9d1fca56
4 changed files with 299 additions and 0 deletions
46
docs/wireguard/index.md
Normal file
46
docs/wireguard/index.md
Normal file
|
|
@ -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-<hostname>` (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
|
||||
112
docs/wireguard/opencode-studio.md
Normal file
112
docs/wireguard/opencode-studio.md
Normal file
|
|
@ -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 <command> [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 <n>` | MLX port | 11434 |
|
||||
| `-s, --server <host>` | 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)
|
||||
76
docs/wireguard/vpn-setup.md
Normal file
76
docs/wireguard/vpn-setup.md
Normal file
|
|
@ -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 <command> [options]
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `up <hostname>` | Full setup: generate keys + bootstrap + start tunnel |
|
||||
| `add <hostname>` | Generate keys and store in Bitwarden (no local setup) |
|
||||
| `rm <hostname>` | Remove peer from Bitwarden |
|
||||
| `list` | List all peers from Bitwarden |
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `-s, --server <ip>` | VPN server endpoint | required |
|
||||
| `-p, --port <port>` | VPN server port | 51820 |
|
||||
| `-S, --subnet <prefix>` | VPN subnet prefix | 10.0.0 |
|
||||
| `-i, --interface <name>` | 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
|
||||
65
docs/wireguard/wg.md
Normal file
65
docs/wireguard/wg.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
layout: default
|
||||
title: wg
|
||||
parent: WireGuard VPN
|
||||
---
|
||||
|
||||
# wg
|
||||
|
||||
Daily WireGuard tunnel management for macOS.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
wg <command> [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>` | Enable/disable auto-start on boot |
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `-i, --interface <name>` | 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)
|
||||
Loading…
Reference in a new issue