FreeGuard VPN Setup Guide

Use when a user wants to set up, use, or troubleshoot FreeGuard VPN - guides non-technical users through installation, login, connection, and daily usage wit...

Security Scan

The skill is an instruction-only VPN setup guide whose declared network, filesystem, and privilege needs match a VPN CLI installer; nothing in the SKILL.md suggests it will do more than instruct the user to run the vendor CLI.

Purpose & Capability

The skill's purpose (FreeGuard VPN setup/troubleshooting) aligns with the listed permissions (access to ~/.freeguard, network access to freeguardvpn.com and GitHub). One minor inconsistency: registry metadata earlier stated 'required binaries: none' while the SKILL.md clearly declares a dependency on a 'freeguard' CLI binary and provides a brew install command.

Instruction Scope

SKILL.md is instruction-only and limits agent actions to guiding the user and running the vendor CLI via the user's terminal. It explicitly states it will not transmit credentials or download binaries itself and requires explicit user consent for installs and sudo. The agent-facing content references local config paths and flags for internal use only—this is expected for a CLI guide but should be followed as written (i.e., do not echo sensitive paths to end users).

Install Mechanism

No install spec is embedded in the skill (instruction-only). The suggested install paths are Homebrew (tap by the vendor) or GitHub Releases with SHA256 checksums — both are standard release channels. The skill recommends checksum verification rather than running remote install scripts, which is appropriate.

Credentials

The skill requests no environment variables or unrelated credentials. Filesystem access to ~/.freeguard and HTTPS access to the vendor domain and GitHub are proportional to installing and using a VPN CLI. Credential-handling is described as happening only in the vendor CLI and stored locally (0600).

Persistence & Privilege

The skill is not always-on and is user-invocable; autonomous invocation is allowed by default but not combined with other red flags. Elevated privileges (sudo) are optional and require explicit user consent in the workflow, which is appropriate for enabling TUN mode.

Assessment

This skill appears coherent for its stated purpose (guiding non-technical users through installing and using the FreeGuard CLI). Before installing or following steps, verify the vendor and release channels yourself: 1) confirm the Homebrew tap is the vendor's official tap and inspect the formula if possible; 2) when using GitHub Releases, verify the SHA256 checksum against the vendor's published checksums; 3) be aware the CLI is proprietary — review vendor docs and reputation before trusting it with credentials; 4) never paste credentials or long-lived tokens into chat; enter them directly into the CLI when prompted; and 5) the skill instructs the agent to run terminal commands—ensure the agent asks for explicit consent before running installs or elevated commands (as the skill mandates). The small metadata mismatch about 'required binaries' is likely a packaging oversight but worth noting.

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.

Security Model

This skill is an instruction-only guide — it does not download, execute, or transmit anything on its own. All operations are performed by the freeguard CLI binary, which the user installs separately through verified channels.

Trust Boundaries

Boundary	Detail
This skill does NOT	download binaries, store credentials, make network requests, or execute code autonomously
This skill DOES	instruct the agent to run freeguard CLI commands via the user's terminal with standard tool-call permissions
Credential flow	User → freeguard CLI → freeguardvpn.com (HTTPS). This skill never touches credentials directly.
Elevated privileges	Optional. Always requires explicit user consent before sudo. A non-elevated fallback is always offered.
Installation	Via Homebrew (signed formula, checksum-verified) or GitHub Releases (SHA256 checksum verification required before install). No remote scripts are executed.
Data exfiltration	None. No data is sent to any domain other than freeguardvpn.com by the CLI. This skill sends no data anywhere.

User Consent Gates

The agent MUST obtain explicit user confirmation before each of these actions:

1. Installing the CLI binary (any method)
2. Running sudo or requesting Administrator privileges
3. Sending a verification code to the user's email
4. Creating a subscription (initiating payment)

The agent must NEVER proceed with any of the above without the user's explicit "yes".

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
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

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:

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. Only two verified installation methods are supported:

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

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 B: 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.

# 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

IMPORTANT: Do NOT proceed if checksum verification fails. Tell the user:

"The checksum didn't match — the download may be corrupted or tampered with. Let's try downloading again."

If checksum passes, extract and install. Ask for user confirmation before running sudo:

"Checksum verified — the download is authentic. I need to move the binary to /usr/local/bin, which requires admin permission. Is that OK?"

Only after user confirms:

# 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

Post-install verification

After install (any method), verify with:

freeguard doctor --json

Step 3: Subscribe (if no subscription)

First check if user already has a subscription:

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:

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:

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:

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:

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:

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:

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:

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:

freeguard connect --json

Connect with smart node selection (v0.8.0+)

The connect command supports multiple ways to specify a server:

# 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:

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)