veteran

SOCKS5 proxy client with subscription support — distributed via npm.

Install

macOS / Linux (Homebrew)

brew install veteran-cli/homebrew-veteran/veteran

Via npm (Cross-platform)

# Global install (use `veteran` command anywhere)
npm install -g veteran

# Or temporary use
npx veteran list

Quick Start

# 1. Update subscription (or set VETERAN_SUB_URL env var and just run `veteran sub`)
veteran sub -u "https://example.com/subscribe?token=xxx"

# 2. List available nodes
veteran list

# 3. Start SOCKS5 proxy
veteran run -n 1 -p 1088

# 4. Check status
veteran status

# 5. Stop when done
veteran stop

Usage

Update Subscription

Fetch proxy nodes from subscription URL:

# Via CLI argument
veteran sub -u "https://example.com/subscribe?token=xxx"

# Or via environment variable (no -u needed)
export VETERAN_SUB_URL="https://example.com/subscribe?token=xxx"
veteran sub

List Nodes

View available nodes with indices:

veteran list

Output format: [TYPE] Name Server:Port

Start Proxy

Basic usage (background mode, default port 1088):

veteran run -n 1 -p 1088

Routing Modes (-m flag):

• 0 — Bypass mainland China
• 1 — Bypass LAN
• 2 — Bypass China + LAN (default)
• 3 — Global proxy
• 4 — Custom rules

Foreground mode (-f flag):

veteran run -n 1 -p 1088 -f

Custom rules (mode 4):

veteran run -n 1 -p 1088 -m 4 \
  --rule "DOMAIN-SUFFIX,google.com,PROXY" \
  --rule "IP-CIDR,192.168.1.0/24,DIRECT" \
  --rule "FINAL,PROXY"

Rule format: TYPE,VALUE,POLICY

• Types: DOMAIN-SUFFIX, DOMAIN-KEYWORD, DOMAIN, IP-CIDR, IP, FINAL
• Policies: PROXY, DIRECT

Rule file (--rule-file):

veteran run -n 1 -p 1088 -m 4 --rule-file ./rules.json

Rule file format (JSON):

{
  "china_domain": ["baidu", "zhihu", "weibo"],
  "china_cidr": ["114.114.114.0/24", "223.5.5.0/24"],
  "private_cidr": [
    "10.0.0.0/8",
    "172.16.0.0/12",
    "192.168.0.0/16",
    "127.0.0.0/12"
  ],
  "custom_rule": [
    "DOMAIN-SUFFIX,google.com,PROXY",
    "DOMAIN-SUFFIX,github.com,PROXY",
    "DOMAIN,www.baidu.com,DIRECT",
    "DOMAIN-KEYWORD,facebook,PROXY",
    "IP-CIDR,192.168.1.0/24,DIRECT",
    "IP,8.8.8.8,PROXY",
    "FINAL,PROXY"
  ]
}

Rule syntax: TYPE,VALUE,POLICY

| TYPE | Description | Example | |------|-------------|---------| | DOMAIN-SUFFIX | Match domain suffix | DOMAIN-SUFFIX,google.com,PROXY | | DOMAIN-KEYWORD | Match domain keyword | DOMAIN-KEYWORD,facebook,PROXY | | DOMAIN | Match exact domain | DOMAIN,www.baidu.com,DIRECT | | IP-CIDR | Match IP range (CIDR) | IP-CIDR,10.0.0.0/8,DIRECT | | IP | Match exact IP | IP,8.8.8.8,PROXY | | FINAL | Default fallback policy | FINAL,PROXY |

Policy values: PROXY (via proxy), DIRECT (direct connection), REJECT (block)

Check Status

veteran status

Shows: PID, port, start time, SOCKS5 address

Stop Proxy

Stop specific port:

veteran stop -p 1088

Stop all instances:

veteran stop

Other Commands

| Command | Description | |---------|-------------| | veteran sub [-u <URL>] | Update subscription (use -u or VETERAN_SUB_URL env var) | | veteran list | List available nodes | | veteran run -n <node> -p <port> | Start SOCKS5 proxy | | veteran status | Check running status | | veteran stop [-p <port>] | Stop proxy instance | | veteran version | Show version |

Multi-Instance Support

Run multiple proxy instances on different ports:

export VETERAN_ALLOW_MULTIPLE=true
veteran run -n 1 -p 1080
veteran run -n 2 -p 1081

Node Selection

The -n flag accepts:

• Index: Number starting from 1 (e.g., -n 1)
• Name: Exact or partial match (e.g., -n "Hong Kong")

Environment Variables

| Variable | Description | |----------|-------------| | VETERAN_SUB_URL | Preset subscription URL, then veteran sub needs no -u | | VETERAN_ALLOW_MULTIPLE | Allow multiple instances (default: false) | | VETERAN_DATA_DIR | Custom data directory (default: ~/.veteran) |

Data Files

Stored in ~/.veteran/ (or VETERAN_DATA_DIR):

• nodes.json — Subscription node list
• veteran-{port}.pid — PID file for instance
• veteran-{port}.log — Log file for instance
• veteran.log — General log

Browser Configuration

Set SOCKS5 proxy in browser/system:

• Address: 127.0.0.1
• Port: As specified (default 1088)

Supported Platforms

| OS | amd64 | arm64 | 386 | armv7 | armv6 | |---------|-------|-------|------|-------|-------| | macOS | ✅ | ✅ | ❌ | ❌ | ❌ | | Linux | ✅ | ✅ | ✅ | ✅ | ✅ | | Windows | ✅ | ✅ | ✅ | ❌ | ❌ |

How it works

This npm package is a thin wrapper. On npm install, it:

1. Detects your platform and architecture
2. Downloads the correct binary from https://laogou.us/download/veteran
3. Extracts it to bin/
4. Exposes it via the veteran CLI command

The binary is only downloaded once — on subsequent installs, if the binary exists, it's reused.

Programmatic API

const veteran = require('veteran');

// Get version
console.log(veteran.version());

// Get binary path
console.log(veteran.path());

// Run a command
const child = veteran.run(['list']);

Troubleshooting

1. Port already in use: Choose a different port with -p
2. Instance already running: Use VETERAN_ALLOW_MULTIPLE=true or stop existing instance
3. Subscription fails: Check URL accessibility and network connection
4. Node not found: Use veteran list to verify node index/name
5. Binary not downloaded: Ensure internet connection; download manually from https://laogou.us/download/veteran and place in PATH

Links

• Source Code
• Issues