Codex VPN

A VPN CLI for Codex sessions.

Codex can manage VPN state through Free VPN CLI when it has SKILL.md and uses JSON output. Keep actions bounded: read current status, choose a region or service preset only when the task needs it, connect, verify, and summarize diagnostics.

Download SKILL.md CLI overview

Codex SKILL.md JSON output Exit codes

Works with

Claude

Cursor

Codex

OpenClaw

Hermes+ any MCP tool

Codex 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

Codex setup

Prepare Codex with SKILL.md.

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

Codex preflight

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

Codex 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; Codex should use the CLI.

Codex workflows

Codex tasks that need structured VPN state.

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

VPN state checks

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

Codex workflow

Bounded VPN tasks for Codex coding sessions.

Codex 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

Codex-specific CLI features.

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

Codex 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 Codex FAQ.

Why does Codex 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 Codex install Free VPN CLI?

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

What output should Codex parse?

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

Can Codex 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 Codex.

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

Download SKILL.md Main CLI page