Skip to content

Quick Start

Get from zero to a working selective proxy in about 5 minutes.

Prerequisites

Your ECS server

You need a Linux server outside the firewall (Singapore, Tokyo, US-West, etc.) with:

Requirement Details
OS Any Linux with apt, yum, or apk (Ubuntu 22.04+, CentOS 7+, Alpine 3.18+ tested)
RAM 512 MB minimum (Squid uses ~30 MB idle)
Disk 1 GB free (Squid + logs)
Network Public IP, outbound internet access
SSH Port 22 reachable from your machine
Firewall Port 22 open. In tunnel mode, no other ports needed. In direct mode, open your Squid port (default 18443) to your IP only

Recommended: Alibaba Cloud Singapore

A 1 vCPU / 1 GB ECS in Singapore costs ~¥30/month and provides low-latency access from mainland China. Any provider works — AWS Lightsail, GCP e2-micro, Vultr, etc.

SSH key access

agent-proxy authenticates via SSH key (no passwords). If you don't have a key yet:

# Generate an Ed25519 key (recommended)
ssh-keygen -t ed25519 -C "agent-proxy"

# Copy it to your ECS
ssh-copy-id -i ~/.ssh/id_ed25519 root@YOUR_ECS_IP

Verify you can connect without a password prompt:

ssh -i ~/.ssh/id_ed25519 root@YOUR_ECS_IP "echo ok"
# Expected: ok

macOS TCC-protected directories

If your SSH key is in ~/Documents/, ~/Desktop/, or ~/Downloads/, background services (LaunchAgent) cannot access it due to macOS TCC restrictions. The init wizard will detect this and offer to copy the key to ~/.ssh/ automatically.

Step 1: Install agent-proxy

# Auto-detect OS/arch, pick fastest mirror, verify SHA-256
curl -fsSL https://raw.githubusercontent.com/chiga0/agent-proxy/main/install.sh | bash

Expected output:

  → Detected: darwin/arm64
  → Downloading agent-proxy v0.7.2 ...
  → Verifying SHA-256 checksum... ✓
  → Installing to /usr/local/bin/agent-proxy
  ✓ agent-proxy v0.7.2 installed

Alternative install methods

# China mirror (faster for CN users)
curl -fsSL https://agent-proxy.oss-cn-hangzhou.aliyuncs.com/install.sh | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/chiga0/agent-proxy/main/install.sh | bash -s -- --version v0.7.2

# Go install (requires Go 1.24+)
GONOSUMDB=github.com/chiga0/agent-proxy go install github.com/chiga0/agent-proxy/cmd/agent-proxy@latest

# Build from source
git clone https://github.com/chiga0/agent-proxy.git
cd agent-proxy && make build

Verify the installation:

agent-proxy version
# Expected: agent-proxy v0.7.2

Step 2: Run the setup wizard

agent-proxy init

The interactive wizard walks you through everything. Here's what each step does and what you'll see:

2a. Server connection

  ┌─────────────────────────────────┐
  │   agent-proxy 首次配置向导       │
  └─────────────────────────────────┘

服务器 IP: 1.2.3.4
SSH 用户 [root]:
SSH 密钥路径 [~/.ssh/id_rsa]: ~/.ssh/id_ed25519
代理端口 [18443]:
  • Server IP: Your ECS public IP address (no http:// prefix).
  • SSH user: Defaults to root. Use a different user if your ECS requires it.
  • SSH key path: Path to your private key. Defaults to ~/.ssh/id_rsa.
  • Proxy port: The port Squid will listen on. Default 18443 is fine for most setups.

2b. SSH tunnel choice

─── SSH 隧道 ───
  启用 SSH 加密隧道? (中国用户推荐) [Y/n]:

Press Enter to accept the default (yes). This is strongly recommended for users in China:

  • Squid listens on 127.0.0.1 only — no public data port exposed
  • All proxy traffic is encrypted via SSH
  • No need to open firewall ports beyond SSH (22)

If you choose "n" (direct mode), Squid listens on all interfaces and is protected only by an IP whitelist. You'll need to ensure your ECS security group restricts the Squid port.

2c. Host key verification

─── 主机验证 ───
  → 获取 1.2.3.4 主机密钥... ✓

  主机密钥指纹:
    256 SHA256:AbCdEf123456789... (ED25519)

  请核对以上 SHA256 指纹与 ECS 控制台一致。
  输入 yes 确认: yes
  ✓ 已保存到 ~/.config/agent-proxy/known_hosts

The wizard fetches your ECS host key and displays its SHA256 fingerprint. Verify this matches your ECS console before typing yes. This prevents man-in-the-middle attacks on your SSH connection.

The key is stored in a project-specific known_hosts file (~/.config/agent-proxy/known_hosts) with StrictHostKeyChecking=yes — subsequent connections will reject any key mismatch.

2d. SSH connectivity + Squid deployment

─── 连接检查 ───
  → SSH 连接... ✓

─── 服务器部署 ───
  → Connectivity... ✓
  → Install Squid... ✓
  → System tuning... ✓
  → Write Squid config... ✓
  → Cleanup legacy... ✓

The wizard SSHes into your ECS and:

  1. Installs Squid via the system package manager (apt/yum/apk)
  2. Enables TCP fast open for better performance
  3. Writes a deny-first Squid config (loopback-only in tunnel mode)
  4. Validates the config syntax, restarts Squid, and verifies it's running
  5. Cleans up any legacy Basic auth files from older versions

2e. Tunnel + local activation

─── SSH 隧道 ───
  → 建立 SSH 隧道... ✓

  ✓ 配置已保存: ~/.config/agent-proxy/config.yaml

─── 本地启用 ───
  → SSH tunnel... ✓
  → PAC server... ✓

✓ Proxy enabled
  PAC (browser/desktop): http://127.0.0.1:18080/proxy.pac
  CLI env:               ~/.config/agent-proxy/env.sh
  Proxy:                 127.0.0.1:18443 (via SSH tunnel → 1.2.3.4:18443)
  Network service:       Wi-Fi
  Whitelist:             61 domains (presets: [ai dev search cloud media])

2f. Connectivity verification

─── 连通性验证 ───
  → google.com           ✓ 200 0.35s
  → github.com           ✓ 200 0.28s
  → youtube.com          ✓ 200 0.41s

  🎉 配置完成！

Step 3: Set up your shell profile

Add this line to ~/.zshrc (or ~/.bashrc):

[ -f "$HOME/.config/agent-proxy/env.sh" ] && source "$HOME/.config/agent-proxy/env.sh"

Then reload your current terminal:

source ~/.config/agent-proxy/env.sh

What does this do? The env.sh file exports three environment variables:

export https_proxy='http://127.0.0.1:18443'
export http_proxy='http://127.0.0.1:18443'
export no_proxy='localhost,127.0.0.1,::1,10.*,...,.alibaba-inc.com,.baidu.com,...'
  • https_proxy / http_proxy — tells CLI tools (curl, pip, npm, etc.) to route through the local SSH tunnel endpoint.
  • no_proxy — tells CLI tools to skip the proxy for localhost, private IPs, and domestic services.

Without sourcing this file, only browsers (via PAC) will use the proxy. CLI tools will go direct.

Step 4: Verify everything works

# Quick health check (6 checks)
agent-proxy status

Expected output:

  ✓ SSH (22) (via tunnel — direct check skipped)
  ✓ SSH tunnel (127.0.0.1:18443 → 1.2.3.4:18443)
  ✓ Proxy forwarding (exit IP: 1.2.3.4)
  ✓ System PAC (http://127.0.0.1:18080/proxy.pac)
  ✓ PAC file (61 domains)
  ✓ PAC HTTP server (127.0.0.1:18080)

  Result: 6 passed, 0 failed

# Full diagnostics (includes no_proxy coverage analysis)
agent-proxy doctor

# Test a proxied request from CLI
curl -s https://httpbin.org/ip
# Should return your ECS IP, not your local IP

# Test that domestic sites go direct
curl -s https://www.baidu.com > /dev/null && echo "direct OK"

What Just Happened?

Here's a summary of everything agent-proxy init set up:

Component Location Purpose
Config file ~/.config/agent-proxy/config.yaml All settings (host, port, presets, no_proxy)
SSH known_hosts ~/.config/agent-proxy/known_hosts ECS host key for StrictHostKeyChecking
PAC file ~/.config/agent-proxy/proxy.pac Generated JavaScript for browser routing
Env file ~/.config/agent-proxy/env.sh Shell exports for CLI proxy
PAC state ~/.config/agent-proxy/pac-state.json Snapshot of original PAC for safe restore
PID file ~/.config/agent-proxy/pac-server.pid PAC daemon process tracking
Nonce file ~/.config/agent-proxy/pac-nonce PAC server identity verification
SSH control socket ~/.config/agent-proxy/ssh-ctrl-* ControlMaster connection multiplexing
ECS Squid config /etc/squid/squid.conf (on ECS) Deny-first proxy ACLs
Auto-start LaunchAgent / systemd / Scheduled Task Start proxy on login

Upgrading

# Self-update with SHA-256 verification
agent-proxy update

Upgrading from < v0.6.0

Two extra steps are needed for older installations:

# Migrate SSH host key to project-specific known_hosts
agent-proxy trust-host

# Rewrite ECS Squid config for loopback-only binding
agent-proxy setup

Next Steps