Terminal Proxy Workflow for Developers

FreeGuard CLI turns your terminal into a secure development environment by routing traffic through encrypted VPN tunnels. Whether you are cloning repositories from restricted networks, debugging APIs across regions, or deploying containers through secure channels, the CLI integrates into the tools you already use — git, ssh, curl, docker, and more.

Why Developers Need a Terminal Proxy

Many development tasks involve network access that benefits from VPN protection:

• Accessing internal APIs from coffee shops or airports
• Testing geo-restricted services during development
• Pushing code over networks that throttle or inspect git traffic
• Connecting to remote servers through restrictive firewalls
• Keeping CI/CD credentials encrypted in transit

FreeGuard CLI handles all of this without leaving your terminal.

Git Over VPN

The Problem

Corporate networks, public Wi-Fi, and some ISPs throttle or block git operations. SSH-based git connections can be flagged by deep packet inspection. HTTPS clones may be intercepted by transparent proxies.

The Solution

Connect to FreeGuard before your git operations:

freeguard connect --server us-east

git clone [email protected]:your-org/private-repo.git
git fetch --all
git push origin feature-branch

freeguard disconnect

For a more automated approach, wrap it in a script:

#!/bin/bash
freeguard connect --server us-east --json | jq -r '.status'
trap "freeguard disconnect" EXIT

git pull origin main
npm run build
git push origin main

The trap ensures VPN disconnects even if the script fails midway.

Proxy-Aware Git

FreeGuard CLI can also expose a local SOCKS5 or HTTP proxy. Configure git to use it:

# Set proxy for git globally
git config --global http.proxy socks5://127.0.0.1:1080
git config --global https.proxy socks5://127.0.0.1:1080

# Or per-repository
git config http.proxy socks5://127.0.0.1:1080

Remove the proxy config when done:

git config --global --unset http.proxy
git config --global --unset https.proxy

SSH Tunneling with VPN

Remote Server Access

When you need to SSH into servers from untrusted networks, VPN adds an encryption layer before your SSH traffic even leaves your machine:

freeguard connect --server us-west
ssh [email protected]

ProxyJump Through VPN

Combine FreeGuard with SSH ProxyJump for multi-hop access:

# Connect to VPN first
freeguard connect

# Then jump through a bastion host
ssh -J [email protected] [email protected]

Port Forwarding

Forward remote ports through the VPN tunnel:

freeguard connect --server eu-west
ssh -L 5432:db.internal:5432 [email protected]
# Now connect to localhost:5432 to reach the remote database

API Development

Testing with curl

Route your API requests through VPN to test from different regions:

freeguard connect --server jp-tokyo

# Test geo-specific API responses
curl -s https://api.example.com/v1/content | jq '.region'
# Output: "ap-northeast-1"

freeguard connect --server de-frankfurt
curl -s https://api.example.com/v1/content | jq '.region'
# Output: "eu-central-1"

Using httpie

httpie works the same way. FreeGuard CLI operates at the system level, so all HTTP clients benefit:

freeguard connect --server uk-london
http GET https://api.example.com/v1/pricing Accept:application/json

Proxy Mode for Selective Routing

If you only want certain requests to go through VPN, use the local proxy:

# Start FreeGuard with local proxy
freeguard connect

# Route specific requests through the proxy
curl --proxy socks5://127.0.0.1:1080 https://api.example.com/endpoint

# Direct requests bypass VPN
curl https://internal.company.com/api

Docker Containers + VPN

Container Network Through VPN

Route Docker container traffic through FreeGuard:

# Connect host to VPN
freeguard connect --server us-east

# Containers using host network will route through VPN
docker run --network host my-app:latest

Docker Compose Integration

Add VPN connectivity to your development stack:

#!/bin/bash
# dev-start.sh
freeguard connect --server us-east --json | jq -r '.status'
docker compose up -d
echo "Development stack is running through VPN"

Building Images Behind Restrictive Networks

When docker build needs to download packages from registries that are blocked or slow:

freeguard connect --server us-west
docker build --network host -t my-app:latest .
freeguard disconnect

CI/CD Integration

GitHub Actions

Use FreeGuard CLI in your CI pipeline to access geo-restricted resources during builds:

- name: Connect VPN
  run: |
    curl -fsSL https://cli.freeguard.com/install.sh | bash
    freeguard login --method token --token ${{ secrets.FREEGUARD_TOKEN }}
    freeguard connect --server us-east --json

Script-Friendly Output

Every FreeGuard CLI command supports --json for machine-readable output and --no-color for clean log files:

# Get connection status as JSON
freeguard status --json
# {"connected": true, "server": "us-east-1", "protocol": "hysteria2", "uptime": 3600}

# List servers as JSON for programmatic selection
freeguard servers --json --region us | jq '.[0].id'

Exit Codes

The CLI uses standard exit codes that scripts can check:

freeguard connect --server us-east
if [ $? -eq 0 ]; then
  echo "VPN connected, starting deployment..."
  ./deploy.sh
fi

Tips for Daily Use

1. Shell alias — Add alias vpn="freeguard connect" and alias vpnoff="freeguard disconnect" to your shell profile.
2. Auto-connect — Add freeguard connect to your .zshrc or .bashrc if you always want VPN on.
3. Server bookmarks — Use freeguard config set default-server us-east to skip the --server flag.
4. Status in prompt — Parse freeguard status --json to show VPN status in your shell prompt.

Next Steps

• FreeGuard CLI — installation and full command reference
• CLI command documentation — detailed reference for every command and flag
• Deploy on headless servers — run FreeGuard CLI as a system service
• Pricing — developer-friendly plans

Last updated: March 2026