Claude Code VPN

A VPN CLI for Claude Code sessions.

Claude Code can use Free VPN CLI most safely when SKILL.md is in context. The workflow is command-first: inspect status as JSON, list regions or service presets when needed, connect, verify, and run doctor only when troubleshooting.

Download SKILL.md CLI overview

Claude Code SKILL.md JSON output Exit codes

Works with

Claude

Cursor

Codex

OpenClaw

Hermes+ any MCP tool

Claude Code shell

$ freevpn status --json

$ freevpn regions --json

$ freevpn set-region "US East"

$ freevpn up --json

$ freevpn doctor --json

# structured output before network assumptions

#1 Free VPN

App Store · Play Store · Mac

100M+

Installs worldwide

10+ yrs

Battle-tested VPN core

1,000+

Servers · global exits

Claude Code setup

Prepare Claude Code with SKILL.md.

Add SKILL.md to Claude Code context before asking it to manage VPN state.

Claude Code preflight

Have Claude Code check install, read status, and use diagnostics rather than guessing.

Paste in Terminal

$command -v freevpn >/dev/null 2>&1 && freevpn version --json

$freevpn status --json

$freevpn regions --json

$freevpn doctor --json

Claude Code guardrails

Ask before installing or changing service state.
Prefer status --json as the authoritative state check.
Use doctor --json before troubleshooting summaries.
Keep GUI mentions human-facing; Claude Code should use the CLI.

Claude Code workflows

Claude Code tasks that need structured VPN state.

Use Claude Code for bounded network work: inspect, change only when asked, verify, and report.

VPN state checks

Ask Claude Code to inspect state before a network-sensitive command.

Region-specific tests

Switch region only when requested and verify status afterward.

Network diagnostics

Use doctor output when API calls or tests fail.

Repo instructions

Keep SKILL.md available so Claude Code follows documented behavior.

How it works

up. status. down.

Three verbs cover most day-to-day VPN work. set-region and doctor cover region selection and troubleshooting.

1 Check where you are · connect

freevpn status · up

user@shell $ freevpn status

VPN : disconnected

region : Fastest (auto)

your IP : 122.179.8.116

location : Bengaluru, India

user@shell $ freevpn up

Connected to Fastest (auto)

your IP : 85.195.125.198

location: Frankfurt, Germany

2 Switch region · verify · disconnect

freevpn set-region · status · down

user@shell $ freevpn set-region "US East"

Switched to US East

user@shell $ freevpn status

VPN : connected

region : US East

your IP : 23.108.55.113

location : Miami, United States

user@shell $ freevpn down

tunnel down · routes restored

Claude Code workflow

Bounded VPN tasks for coding sessions.

Claude Code should use a small repeatable command set and explain any network state changes it makes.

Paste in Terminal

$freevpn status --json

$freevpn regions --json

$freevpn set-region "US East"

$freevpn up --json

$freevpn status --json

$freevpn doctor --json

Command	Why it matters
`freevpn status --json`	Read current VPN state before acting.
`freevpn regions --json`	Inspect available regions.
`freevpn set-region "US East"` `freevpn up --json`	Connect to a requested region with parseable output.
`freevpn doctor --json`	Collect diagnostics before making network claims.

Features

Claude Code-specific CLI features.

Claude Code benefits from the same agent-safe primitives: SKILL.md, JSON, exit codes, and doctor diagnostics.

Agent guidance

Works with Claude, Cursor, Codex, OpenClaw, Hermes, and any MCP tool. SKILL.md explains GUI scope, install checks, command names, and troubleshooting.

Structured output

Use JSON for any command Claude Code needs to parse.

Exit-code handling

Branch on documented outcomes instead of guessing from text.

Troubleshooting recipes

Doctor output gives structured evidence for summaries.

Region commands

List, set, connect, and verify region changes.

CLI authority

Use CLI status as authoritative over GUI screenshots.

Service presets

Use service presets without scraping the app UI.

SKILL.md documents freevpn services so agents can list service categories, inspect the current preset, or choose Off and General without reading screenshots. Non-default service presets are paid and return license_required for free users.

freevpn services list shows supported service presets.
freevpn services categories groups presets such as Streaming, Sports, Social, AI, and Other where available.
freevpn services current prints the current preset name on one line.
freevpn services --json is the safest form for scripts and agents.

Paste in Terminal

$freevpn services list

$freevpn services categories

$freevpn services current

$freevpn services --json

Practical notes

Claude Code safety notes.

The safest workflow is explicit, parseable, and easy for the user to review.

Ask before install or service changes.
Use command -v freevpn and version --json before assuming install.
Treat status --json as authoritative.
Use doctor --json for network failures.

FAQ

VPN for Claude Code FAQ.

Why does Claude Code need SKILL.md?

The skill documents how an agent should use Free VPN CLI safely: commands, JSON output, exit codes, GUI scope, and diagnostics.

Can Claude Code install Free VPN CLI?

It can run or guide the documented installer, but OS permission prompts still need normal user approval.

What output should Claude Code parse?

Use --json for every command it needs to parse.

Can Claude Code use the GUI?

It should use the CLI directly. The GUI is for humans and shares the same daemon.

What is the best diagnostic command?

Use freevpn doctor --json.

Use Free VPN CLI safely from Claude Code.

Give Claude Code SKILL.md and keep VPN work structured through JSON commands and doctor diagnostics.

Download SKILL.md Main CLI page