FreeGuard VPN Setup Guide

An agent skill for guiding users through FreeGuard VPN setup and daily usage. Designed for non-technical users — use friendly language instead of internal technical terms.

Required Tools

This skill requires the freeguard CLI binary. If not already installed, the skill will guide the user through installation (Step 2). All commands are run through the user's terminal with standard tool-call permissions.

| Binary | Install (recommended) | Purpose | |--------|-----------------------|---------| | freeguard | brew install planetlinkinc/tap/freeguardvpn | VPN CLI — all operations in this skill depend on it |

Vendor & Domain Information

FreeGuard VPN is developed by Planetlink Inc.

| Purpose | Domain | Notes | |---------|--------|-------| | Homepage | https://freeguardvpn.com | Product homepage | | GitHub Releases | github.com/planetlinkinc/freeguard-releases | Public repo — binary releases with SHA256 checksums | | Homebrew tap | github.com/planetlinkinc/homebrew-tap | Public repo — signed formula, downloads from GitHub Releases | | Install scripts | downloadcli.freeguardvpn.com | Convenience install scripts (Option 3) | | API backend | www.freeguardvpn.com | Login, subscription, profile sync |

The CLI source code is proprietary (not open-source). All credentials are sent exclusively to freeguardvpn.com over HTTPS. No other domains receive user data.

Credentials & Data Handling

• Email: asked from user for login/subscription, sent to freeguardvpn.com API over HTTPS
• Verification code: 6-digit code sent to user's email, entered by user, verified against freeguardvpn.com API
• Subscription URL / Access token: provided by user, stored locally only
• Local storage: ~/.freeguard/credentials.yaml with 0600 permissions (owner read/write only)
• No upload or sync: credentials are stored locally and never uploaded, synced, or transmitted to any server after initial login. The CLI reads them locally for subsequent operations.
• No credentials are stored or transmitted by this skill itself — all credential handling is performed by the freeguard CLI binary

Tone

When speaking to the user, always use friendly, non-technical language:

• Simple phrasing: "open your terminal" not "execute in shell"
• Celebrate progress: "Great, you're logged in!"
• If something fails, reassure: "No worries, let's try another way"
• Never expose internal terms to the user: say "settings" not "YAML", "VPN engine" not "mihomo", "smart routing" not "rule-provider" (see Language Guide below for full mapping)

Note: the agent-facing instructions in this document reference file paths, config keys, and CLI flags — these are for the agent's internal use and should NOT be repeated verbatim to the user.

Agent Flow

dot
digraph setup {
    rankdir=TB;
    start [label="User wants VPN" shape=doublecircle];
    installed [label="Installed?" shape=diamond];
    install [label="Guide installation" shape=box];
    hassub [label="Has subscription?" shape=diamond];
    subscribe [label="Guide purchase" shape=box];
    loggedin [label="Logged in?" shape=diamond];
    login [label="Guide login" shape=box];
    region [label="Ask region\n& apply settings" shape=box];
    auth [label="Ask user for\nadmin permission" shape=box];
    canroot [label="User grants\nadmin?" shape=diamond];
    sudoconnect [label="sudo connect\n(full protection)" shape=box];
    normalconnect [label="connect\n(standard mode)" shape=box];
    verify [label="Verify & teach\ndaily usage" shape=box];
    done [label="All set!" shape=doublecircle];

    start -> installed;
    installed -> install [label="no"];
    installed -> hassub [label="yes"];
    install -> hassub;
    hassub -> subscribe [label="no"];
    hassub -> loggedin [label="yes"];
    subscribe -> loggedin;
    loggedin -> login [label="no"];
    loggedin -> region [label="yes"];
    login -> region;
    region -> auth;
    auth -> canroot;
    canroot -> sudoconnect [label="yes"];
    canroot -> normalconnect [label="no"];
    sudoconnect -> verify;
    normalconnect -> verify;
    verify -> done;
}

Step 1: Check Environment

Run the diagnostic command and summarize the result to the user:

bash
freeguard doctor --json

From the result, determine:

• Not installed → Go to Installation
• Installed, no subscription → Go to Subscribe
• Installed, has subscription but not logged in → Go to Login
• Logged in with subscription → Go to Region & Connect

Tell the user the current state in friendly terms:

• "Looks like FreeGuard isn't installed yet. Let me help you set it up!"
• "FreeGuard is installed! Now we need to get you a subscription."
• "You have a subscription but aren't logged in yet. Let's fix that."
• "You're already logged in! Let's get you connected."

Step 2: Installation

Ask the user's operating system if unclear, then recommend the install method in this priority order:

Option 1 (Recommended): Homebrew (macOS / Linux)

bash
brew install planetlinkinc/tap/freeguardvpn

Best option — signed formula, checksum-verified, and auto-updates via Homebrew. The formula source is public at github.com/planetlinkinc/homebrew-tap.

Option 2: GitHub Release (macOS / Linux / Windows)

Download pre-built binaries directly from the official GitHub Releases page. Each release includes SHA256 checksums for verification.

> "I can download FreeGuard from the official GitHub releases page. This is a verified download with checksum — would you like me to go ahead?"

Only proceed after user explicitly confirms.

bash
# Step 1: Download the binary and checksum file from GitHub Releases
# Replace <VERSION> and <ASSET> with the latest release info
curl -fsSL https://github.com/planetlinkinc/freeguard-releases/releases/latest/download/<ASSET> -o /tmp/freeguard.tar.gz
curl -fsSL https://github.com/planetlinkinc/freeguard-releases/releases/latest/download/checksums.txt -o /tmp/checksums.txt

# Step 2: Verify checksum before installing
cd /tmp && shasum -a 256 -c checksums.txt --ignore-missing

If checksum passes, extract and install:

bash
# Step 3: Extract and move to PATH
tar xzf /tmp/freeguard.tar.gz -C /tmp
sudo mv /tmp/freeguard /usr/local/bin/freeguard

To find the correct asset name, check the latest release at: https://github.com/planetlinkinc/freeguard-releases/releases/latest

Asset naming convention:

• macOS (Apple Silicon): freeguard-darwin-arm64.tar.gz
• macOS (Intel): freeguard-darwin-amd64.tar.gz
• Linux (x64): freeguard-linux-amd64.tar.gz
• Windows (x64): freeguard-windows-amd64.zip

Option 3: Install script (convenience)

Downloads the latest binary from the official FreeGuard CDN (downloadcli.freeguardvpn.com). Always download the script first, let the user inspect it, then execute. Ask for explicit confirmation before running.

> "I can also download an install script that automates the process. I'll show you the script first so you can review it. Would you like to try this, or prefer Homebrew / GitHub Release instead?"

Only proceed after user explicitly confirms.

macOS / Linux:

bash
# Step 1: Download the script for inspection
curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh -o /tmp/freeguard-install.sh

# Step 2: Show the user what the script does
cat /tmp/freeguard-install.sh

After showing the script content, tell the user: > "Here's what the install script does: brief summary of the script's actions]. Shall I run it?"

Only after user confirms:

bash
# Step 3: Execute the reviewed script
sh /tmp/freeguard-install.sh

Windows (PowerShell):

powershell
# Step 1: Download the script for inspection
Invoke-WebRequest -Uri https://downloadcli.freeguardvpn.com/cli/install.ps1 -OutFile $env:TEMP\freeguard-install.ps1

# Step 2: Show the user what the script does
Get-Content $env:TEMP\freeguard-install.ps1

After showing the script content, tell the user: > "Here's what the install script does: brief summary]. Shall I run it?"

Only after user confirms:

powershell
# Step 3: Execute the reviewed script
& $env:TEMP\freeguard-install.ps1

Post-install verification

After install (any method), verify with:

bash
freeguard doctor --json

Step 3: Subscribe (if no subscription)

First check if user already has a subscription:

bash
freeguard subscribe info --json

If they have an active subscription, skip to Login. If expired, tell them: > "Your subscription has expired. Let's renew it!"

If no subscription, check available plans:

bash
freeguard subscribe list --json

Then present the options in friendly terms:

> "To use FreeGuard VPN, you'll need a subscription. Here are the plans available: > > | Plan | Price | > |------|-------| > | Weekly | $3.99/week | > | Monthly | $7.99/month | > | Yearly | $49.99/year (best value) | > > Which plan works for you?"

After the user picks a plan, ask for their email:

> "Great choice! What email address should we use for your account?"

Then create the subscription:

bash
freeguard subscribe create --plan <price_id> --email <email> --json

Map user's choice to price_id from the subscribe list response. The command will return a checkout URL.

Tell the user:

> "I've opened a payment page for you. Please complete the payment there, and let me know when you're done."

After they confirm payment, proceed to Login.

Step 4: Login

Ask the user how they'd like to log in:

> "How would you like to log in? > 1. Email — I'll send you a verification code > 2. Subscription link — if you have a Clash subscription URL > 3. Access token — if you received one after purchase"

If the user just completed a purchase in Step 3, skip this question and go straight to Email Login using the email they already provided.

Email Login (most common)

1. Ask: "What's your email address?"
2. Tell user: "I'll send a verification code to your email now."
3. Run: freeguard login --email <email> --send-code --json
4. Tell user: "A verification code has been sent. Please check your inbox (and spam folder) and tell me the 6-digit code."
5. User provides code
6. Run: freeguard login --email <email> --code <code> --json
7. On success: "Great, you're logged in! Your credentials are saved locally on this computer only."
8. On failure: "That code didn't work. Want me to send a new one?"

URL Login

1. Ask: "Please paste your subscription URL"
2. Run: freeguard login --url <url> --json
3. On success: "Logged in successfully!"

Token Login

1. Ask: "Please paste your access token"
2. Run: freeguard login --token <token> --json
3. On success: "Logged in successfully!"

Step 5: Region & Settings

Ask the user where they are:

> "One more thing — where are you located? This helps optimize your connection for the best speed. > > For example: China, Japan, US, Korea, Russia, etc."

Map their answer to a region code:

| User says | Region code | |-----------|-------------| | China / mainland / CN | CN | | US / America / United States | US | | Japan / JP | JP | | Korea / KR / South Korea | KR | | Russia / RU | RU | | Iran / IR | IR | | Indonesia / ID | ID | | UAE / Dubai / AE | AE | | Other / not listed above | (skip GeoIP) |

Tell the user what settings you're applying: > "I'm going to optimize your settings: enable system-wide VPN protection, network sharing, and fast DNS. This will give you the best experience."

Then apply settings:

bash
freeguard config set proxy.tun true --json
freeguard config set proxy.allow_lan true --json
freeguard config set dns.enable true --json

Only if user's region matches one of the 8 supported codes:

bash
freeguard config set geoip_region <CODE> --json

Also ask if the user wants a specific country for their VPN exit: > "Which country do you want to appear as when browsing? For example: US, Japan, Hong Kong..."

If they specify:

bash
freeguard config set preferred_country <country> --json

Tell the user: > "Settings applied! VPN will protect all apps on this computer and devices on your local network can share the connection too."

Step 6: Authorize & Connect

Why admin access is needed

TUN mode creates a virtual network adapter to capture ALL traffic from every app on the system. This is a low-level OS operation that requires elevated privileges:

• macOS / Linux: requires sudo to create the TUN device (/dev/tun*) and modify routing tables
• Windows: requires Administrator to install the Wintun network driver

Without admin access, only apps that respect system proxy settings (browsers, most GUI apps) will go through VPN. Terminal commands, games, and some desktop apps may bypass VPN.

Connecting

macOS / Linux: > "To protect all your apps (not just the browser), VPN needs admin privileges. This is needed to create a virtual network adapter that captures all traffic. > > I'll need to run sudo freeguard connect. Is that OK? You'll be asked for your password."

Only proceed after user confirms. Then run:

bash
sudo freeguard connect --json

Windows: > "To protect all your apps, we need to run as Administrator. This is needed to install a network driver that captures all traffic. > > Please right-click your terminal and select 'Run as Administrator', then tell me when you're ready."

After they confirm:

bash
freeguard connect --json

If user declines admin access: > "No problem! I'll connect in standard mode. Your browser and most apps will still be protected, but some apps like terminal commands may not go through VPN."

Then connect without sudo:

bash
freeguard connect --json

Connect with smart node selection (v0.8.0+)

The connect command supports multiple ways to specify a server:

bash
# Auto-select best node (default)
freeguard connect --json

# Use short alias (e.g. la2 = Los Angeles-2)
freeguard connect la2 --json

# Use country code (uppercase, auto-selects best in that country)
freeguard connect US --json

# Use alias + protocol
freeguard connect la2 anytls --json

# Reconnect to last-used node (no args, remembers previous session)
freeguard connect --json

When the user says "connect to LA" or "use Los Angeles": use the short alias form (e.g. la2). Run freeguard node list --json first to find the matching alias.

When the user says "connect to US" or "use a Japan server": use the country code form (e.g. US, JP).

If the user just says "connect" and they've used VPN before: the CLI automatically reconnects to their last-used node. No extra steps needed.

The connect command runs automatic health checks (DNS, direct access, proxy, streaming, download speed). Parse the JSON output and report to user:

• All 5 checks pass: "You're connected! Everything is working perfectly — browsing, streaming, and downloads all good."
• Some checks fail: "You're connected, but some features need attention..." (explain which failed in simple terms)

On failure, check the error:

• subscription_expired: "Your subscription has expired. Would you like to renew?" → Go to Step 3
• auth_required: "It seems your login session expired. Let's log in again."
• core_download_failed: "There was a download issue. Please check your internet and try again."
• Other: "Something went wrong. Let me run a diagnostic..." → run freeguard doctor --json

Step 7: Verify

Check the connection status and report to the user:

bash
freeguard status --json

If connected, tell the user: > "Everything looks good! Here's what you need to know: > > - Check status: just ask me 'am I connected?' > - Disconnect: ask me to 'disconnect' or run freeguard disconnect > - Reconnect: ask me to 'reconnect' or run freeguard reconnect (restarts the VPN fresh) > - Quick reconnect: just run freeguard connect — it remembers your last server > - Switch server: ask me to 'switch to la2' or 'switch to Japan' — you can use short aliases! > - See all servers: run freeguard node list to see servers with their short aliases > - Check subscription: ask me 'when does my plan expire?' > - Start on boot: ask me to 'enable autostart' > - Shell completion: run freeguard completion bash (or zsh/fish/powershell) to enable tab completion > > Enjoy your secure internet!"

Daily Usage Commands

When the user asks about ongoing usage, run the appropriate command and summarize the result in friendly terms:

| User says | What to do | |-----------|------------| | "Am I connected?" / "Status" | freeguard status --json → report connection, node, mode, subscription expiry | | "Connect" / "Turn on VPN" | freeguard connect --json → auto-reconnects to last-used node, or auto-selects best | | "Connect to US" / "Use Japan server" | freeguard connect US --json (country code, uppercase) | | "Connect to LA" / "Use Los Angeles" | freeguard connect la2 --json (short alias). Run node list --json first to find the right alias | | "Disconnect" / "Turn off VPN" | freeguard disconnect --json → "Disconnected" | | "Reconnect" / "Restart VPN" | freeguard reconnect --json → full disconnect + reconnect cycle | | "Show nodes" / "Server list" | freeguard node list --json → summarize locations with short aliases | | "Switch to Tokyo" | freeguard node switch to1 --json (use alias). Run node list --json first to find the alias | | "Switch to hysteria2 protocol" | freeguard node switch <alias> hysteria2 --json | | "Speed test" | freeguard node test --all --json → show top 5 fastest | | "Check my account" | freeguard subscribe info --json → report plan status and expiry | | "Renew my subscription" | freeguard subscribe list --json → show plans | | "Manage billing" | freeguard subscribe portal --email <email> --code <code> → open Stripe portal | | "Something's not working" | freeguard doctor --json → diagnose and suggest fixes | | "Log out" | freeguard disconnect --json then freeguard logout --json | | "Share VPN with my phone" | Explain: set proxy to this computer's IP, port 7997 | | "Start VPN on boot" | freeguard autostart enable --json | | "Stop autostart" | freeguard autostart disable --json | | "Enable tab completion" | freeguard completion bash (or zsh/fish/powershell) → guide user to source the output |

Short Aliases (v0.8.0+)

Nodes have auto-generated short aliases shown in freeguard node list. The alias format is:

• Multi-word city: first letter of each significant word + node number (e.g. la2 = Los Angeles-2, hk1 = Hong Kong-1)
• Single-word city: first 2 letters + node number (e.g. to1 = Tokyo-1, se1 = Seattle-1)
• Collisions: losing city extends to 3 letters (e.g. seo1 = Seoul-1 since se1 = Seattle-1)

Aliases are lowercase. Country codes are uppercase. This is how they are distinguished:

• se1 = Seattle-1 (alias)
• SE = Sweden (country code, auto-selects best node)

When the user wants to connect or switch to a specific server, always look up the alias first via freeguard node list --json and use the alias form — it's shorter and less error-prone than typing full node names with spaces.

Troubleshooting

When things go wrong, run freeguard doctor --json and interpret the results:

| Check fails | What to tell user | |-------------|-------------------| | Network | "Your internet connection seems to be down. Please check your WiFi or cable." | | Credentials | "Your login session has expired. Let's log in again." | | Subscription | "You need an active subscription. Would you like to pick a plan?" → Go to Step 3 | | Subscription expired | "Your subscription has expired. Let's renew it!" → Go to Step 3 | | Port in use | "Another app is using the same port. FreeGuard will find an available one automatically." | | Core Binary | "A component needs to be downloaded. Let me try connecting — it should download automatically." |

Language Guide

Use friendly language instead of internal technical terms:

| Technical term | User-friendly alternative | |----------------|--------------------------| | mixed port 7997 | proxy settings | | TUN mode | system-wide VPN protection | | allow LAN | share VPN with other devices on your network | | GeoIP region CN | optimized for your location in China | | fake-ip DNS | fast DNS | | rule-provider | smart routing | | node switch | switch server | | node alias (la2, to1) | short server name / shortcut | | autostart enable | start VPN on boot | | subscribe info | check your account | | reconnect | restart VPN connection | | completion | tab completion / auto-complete | | Levenshtein / fuzzy match | smart suggestions when you mistype | | Trojan/AnyTLS/Hysteria2 | connection protocols (only mention if user asks) | | mihomo | VPN engine (only mention if user asks) | | config.yaml / runtime.yaml | settings (only mention if user asks) |