USCF (Modified from Usque)

Before using this tool, You need to agree the code License and CloudFlare Tos.

USCF is a 3-party experiment tool that connects to Cloudflare Warp using a unique QUIC-based protocol. This lightweight and high-performance tool provides a simple and easy-to-use SOCKS5 proxy for secure connections to Warp.

This is a tool modified from Usque, my branch mainly improve performace like stable memory usage or high cocurrent efficiency.

Features

• Small, Lightweight, One-Command Automatic Deploy, Simple To Use
• Faster and more portable than using Wireguard Warp
• High Performance under connection pressure
• Docker containerization support

Build from Source

# Clone the repository
git clone https://github.com/HynoR/uscf.git
cd uscf

# Build
go build -o uscf .

Usage

First Use (Automatic Registration)

Before you use this tool, you must accept and follow Cloudflare TOS!!!

The first time you run USCF, it will automatically register a Cloudflare Warp account and create a configuration file:

./uscf proxy -b <bind-addr;default:127.0.0.1> -u <username;default:none> -w <password;default:none> -p <port;default:1080> -c <config.json> --license <WARP+ license;optional>

Use Existing Configuration

If you already have a configuration file, run directly:

./uscf proxy -c config.json

SOCKS-Only Mode

If you only want USCF to expose a SOCKS5 server and let the host or container networking decide the egress path, use socks:

./uscf socks -c config.json -b 0.0.0.0

uscf socks only loads reusable settings from config.json. It does not create a TUN device, does not establish MASQUE, and does not read key.json.

Standalone WireGuard Registration And Profile Generation

If you also want a standard WireGuard profile, use the wg command group. These commands use a separate wg-account.json file and do not depend on config.json or key.json.

Register a standalone WireGuard device:

./uscf wg register --accept-tos --wg-account wg-account.json --name my-device --model PC

Generate a WireGuard profile from the saved account:

./uscf wg generate --wg-account wg-account.json --profile wg-profile.conf

Runtime endpoint selection priority:

• If custom_endpoints_v4 / custom_endpoints_v6 has valid entries for current socks.use_ipv6 family, USCF picks one randomly on each reconnect attempt.
• If custom list is empty or invalid, USCF falls back to endpoint_v4 / endpoint_v6.

Account Modes (account_mode)

USCF uses account_mode in config.json as the startup source of truth:

• free: trial account mode
• premium: personal premium mode
• team: team premium mode

Startup rules

• If config is valid (id + access_token present), USCF reuses it directly.
• If config is invalid/missing, USCF registers a new account:
  • --license => register premium
  • --jwt => register team
  • no flag => register free

Existing premium/team behavior

• If config is valid and account_mode is premium or team, USCF ignores --license and --jwt.
• No Cloudflare registration/license update API is sent in this case.
• When registration is required for premium/team and --name is not provided, USCF auto-generates a short device name:
  • format: <m>-<host>-<id4> (m is p or t)
  • id4 is derived from account id suffix to reduce collisions when many VMs share the same hostname
  • final name is normalized and capped at 16 characters
• If --name is provided, it has priority, and is normalized/capped to 16 characters before registration.

Version switching policy

• Switching versions must go through free first.
• To switch from premium/team, first set account_mode to free, then run with --license or --jwt to register the new mode.
• If you stay in premium/team, repeated startup with flags will not re-register.

Important notes

• License bind success does not always mean immediate warp=plus behavior; Cloudflare side may still present warp=on for affected accounts.
• If you hit that behavior, create a fresh account and bind license immediately (same recommendation as wgcf docs).

Docker Deployment

Build Docker Image

docker build -t uscf:latest .

Build WireGuard SOCKS Docker Image

This customer-oriented image is separate from the normal MASQUE image. It can run in two ways:

• First deployment bootstrap: if /app/etc/config.json, /app/etc/wg-account.json, and /app/etc/wgcf.conf are all missing, the container auto-registers a free WireGuard account, auto-generates wg-account.json + wgcf.conf, then starts uscf socks.
• Existing deployment: pre-populate /app/etc/config.json + /app/etc/wgcf.conf yourself. wg-account.json is optional in this case.

Using the image in first-deployment bootstrap mode means you accept the Cloudflare Terms of Service, because the container will automatically call uscf wg register --accept-tos.

Then build the special image:

docker build -f Dockerfile.wg-socks -t uscf:wg-socks .

RUN

docker run -d   --name uscf   --network=host   -v  /etc/uscf/:/app/etc/   --log-driver json-file   --log-opt max-size=3m   --restart on-failure  --privileged  uscf

RUN WireGuard SOCKS Image

This variant always brings up /app/etc/wgcf.conf with wg-quick, then starts uscf socks -c /app/etc/config.json -b 0.0.0.0.

First deployment with auto bootstrap

Mount a writable directory. Bootstrap is triggered only when /app/etc/config.json, /app/etc/wg-account.json, and /app/etc/wgcf.conf are all missing; unrelated files in /app/etc do not disable it.

docker run -d \
  --name uscf-wg \
  --cap-add=NET_ADMIN \
  --device=/dev/net/tun \
  -p 1080:1080 \
  -v /host/uscf:/app/etc \
  --restart unless-stopped \
  uscf:wg-socks

Generated on first successful startup:

• /app/etc/config.json
• /app/etc/wg-account.json
• /app/etc/wgcf.conf

The generated config.json uses anonymous SOCKS by default. If you want runtime-only overrides, you can append normal uscf socks flags to docker run, for example:

docker run -d \
  --name uscf-wg \
  --cap-add=NET_ADMIN \
  --device=/dev/net/tun \
  -p 1081:1081 \
  -v /host/uscf:/app/etc \
  --restart unless-stopped \
  uscf:wg-socks -p 1081 -u demo -w secret

These flags only affect the running process and do not rewrite config.json.

Existing deployment with pre-generated files

If config.json and wgcf.conf already exist, the container skips registration and profile generation and starts directly:

docker run -d \
  --name uscf-wg \
  --cap-add=NET_ADMIN \
  --device=/dev/net/tun \
  -p 1080:1080 \
  -v /host/uscf/config.json:/app/etc/config.json:ro \
  -v /host/uscf/wgcf.conf:/app/etc/wgcf.conf:ro \
  --restart unless-stopped \
  uscf:wg-socks

Expected existing-deployment layout:

• /host/uscf/config.json -> /app/etc/config.json
• /host/uscf/wgcf.conf -> /app/etc/wgcf.conf
• /host/uscf/wg-account.json -> /app/etc/wg-account.json (optional)

Behavior differences from the normal image:

• Normal image runs uscf proxy and uses MASQUE/TUN.
• WireGuard SOCKS image runs wg-quick up /app/etc/wgcf.conf and then uscf socks.
• In socks mode, tunnel-specific settings such as MASQUE identity, bypass_domain, proxy_tcp_port, block_udp_443, and remote/custom DNS options are ignored.
• Startup state rules are strict:
  • all three of config.json, wg-account.json, wgcf.conf missing => bootstrap
  • config.json + wgcf.conf present => start existing deployment
  • any other partial combination => fail fast instead of auto-repair

Configuration File Description

USCF now uses two JSON files in the same directory:

• config.json: shared/reusable runtime settings (socks, logging, registration, custom_endpoints_*)
• key.json: node-specific Cloudflare/MASQUE identity fields (private_key, endpoint_*, id, access_token, etc.)

The default path passed by -c/--config is still config.json. key.json is always resolved in the same directory.

Configuration Example

After automatic registration, you will get config.json + key.json in the same directory. You can edit items and restart your program to apply them. The Config file is merge from usque's flags and configs, You can find the description of config items from usque.

Time options (dns_timeout, keepalive_period, reconnect_delay, connection_timeout, idle_timeout) use human-readable strings: unit suffixes are ns, us/µs, ms, s, m, h (e.g. "2s", "5m", "1h30m"). Legacy configs with numeric nanosecond values are still accepted.

Logging options are configured in logging:

• level: debug, info, warn, error (default: info)
• format: text, json (default: text)
• socks_verbose: whether to emit SOCKS connection-level diagnostics (default: false)

Reconnect guard option:

• socks.max_reconnect_attempts: maximum consecutive reconnect attempts before pausing retries for manual intervention. 0 means unlimited retry (default).

Bypass domain option:

• socks.bypass_domain: domain allowlist for direct network egress. Matching rule is exact-or-subdomain (example.com matches both example.com and a.example.com).
• When a destination domain matches this list, traffic bypasses MASQUE tunnel and uses the current host network directly.

Proxy TCP port option:

• socks.proxy_tcp_port: TCP destination port allowlist for MASQUE tunnel egress. Example: [80, 443] means only TCP/80 and TCP/443 use TUN; TCP/1001, TCP/992, TCP/1102 go out directly.
• When socks.proxy_tcp_port is non-empty, it takes priority over socks.bypass_domain for TCP routing decisions. DNS behavior still follows socks.remote_dns.

config.json:

{
  "custom