aradotso/skills/microwarp-cloudflare-proxy

---
name: microwarp-cloudflare-proxy
description: Ultra-lightweight Cloudflare WARP SOCKS5 proxy in Docker using kernel-level WireGuard and microsocks, consuming under 800KB RAM
triggers:
  - set up cloudflare warp proxy docker
  - lightweight warp socks5 container
  - microwarp setup and configuration
  - replace caomingjun warp with microwarp
  - cloudflare warp wireguard docker low memory
  - warp proxy with authentication docker
  - bypass cloudflare warp regional blocks
  - warp socks5 proxy under 1mb ram
---

# MicroWARP Cloudflare Proxy

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

MicroWARP is an ultra-lightweight Cloudflare WARP SOCKS5 proxy that runs inside Docker using Linux kernel-level WireGuard (`wg0`) and a pure-C `microsocks` server. It uses **~800KB RAM** and a 9MB image — compared to 150MB RAM and 201MB image for `caomingjun/warp`.

## Architecture

- **WireGuard kernel module** (`wg0`): handles WARP tunnel at kernel level, near-zero CPU
- **microsocks**: pure C SOCKS5 server, no Go/Rust overhead
- **Auto-registration**: fetches free WARP credentials from Cloudflare API on first run
- **Persistent volume**: saves WireGuard config to avoid re-registration on restart

## Installation

### Docker Compose (recommended)

```yaml
# docker-compose.yml
version: '3.8'

services:
  microwarp:
    image: ghcr.io/ccbkkb/microwarp:latest
    container_name: microwarp
    restart: always
    ports:
      - "1080:1080"
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    volumes:
      - warp-data:/etc/wireguard

volumes:
  warp-data:

docker compose up -d
docker compose logs -f   # watch first-run registration

Docker Run (one-liner)

docker run -d \
  --name microwarp \
  --restart always \
  -p 1080:1080 \
  --cap-add NET_ADMIN \
  --cap-add SYS_MODULE \
  --sysctl net.ipv4.conf.all.src_valid_mark=1 \
  -v warp-data:/etc/wireguard \
  ghcr.io/ccbkkb/microwarp:latest

Environment Variables

| Variable | Default | Description | |---|---|---| | BIND_ADDR | 0.0.0.0 | SOCKS5 listen address | | BIND_PORT | 1080 | SOCKS5 listen port | | SOCKS_USER | (empty) | Auth username (empty = no auth) | | SOCKS_PASS | (empty) | Auth password | | ENDPOINT_IP | (auto) | Custom WARP endpoint IP:port (bypass DPI) |

Configuration Examples

With SOCKS5 Authentication

version: '3.8'

services:
  microwarp:
    image: ghcr.io/ccbkkb/microwarp:latest
    container_name: microwarp
    restart: always
    ports:
      - "1080:1080"
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    environment:
      - SOCKS_USER=${WARP_USER}
      - SOCKS_PASS=${WARP_PASS}
    volumes:
      - warp-data:/etc/wireguard

volumes:
  warp-data:

Custom Port + Auth

environment:
  - BIND_ADDR=127.0.0.1   # localhost only
  - BIND_PORT=9050
  - SOCKS_USER=${WARP_USER}
  - SOCKS_PASS=${WARP_PASS}

Bypass Regional Blocks (HK/US DPI)

If Cloudflare's reserved bytes verification blocks your region, inject a clean endpoint IP:

environment:
  - ENDPOINT_IP=162.159.193.10:2408

Scan for clean endpoints using tools like warp-endpoint-scanner and inject the best one.

Localhost-Only Binding (secure setup)

ports:
  - "127.0.0.1:1080:1080"   # only accessible from host
environment:
  - BIND_ADDR=0.0.0.0        # container listens on all interfaces

Usage Patterns

Test the proxy

# Basic connectivity test
curl --socks5 127.0.0.1:1080 https://cloudflare.com/cdn-cgi/trace

# With authentication
curl --socks5-hostname 127.0.0.1:1080 \
  --proxy-user "${WARP_USER}:${WARP_PASS}" \
  https://cloudflare.com/cdn-cgi/trace

# Check your IP via WARP
curl --socks5 127.0.0.1:1080 https://ipinfo.io/json

Use with Python (requests)

import requests

proxies = {
    "http": "socks5://127.0.0.1:1080",
    "https": "socks5://127.0.0.1:1080",
}

# With auth
proxies_auth = {
    "http": "socks5://user:[email protected]:1080",
    "https": "socks5://user:[email protected]:1080",
}

resp = requests.get("https://ipinfo.io/json", proxies=proxies)
print(resp.json())

Use with Node.js

import { SocksProxyAgent } from 'socks-proxy-agent';
import fetch from 'node-fetch';

const agent = new SocksProxyAgent('socks5://127.0.0.1:1080');
// With auth: 'socks5://user:[email protected]:1080'

const res = await fetch('https://ipinfo.io/json', { agent });
console.log(await res.json());

Convert to HTTP Proxy with gost

MicroWARP provides SOCKS5 only. Chain with gost for HTTP:

# Install gost
curl -fsSL https://github.com/go-gost/gost/releases/latest/download/gost_linux_amd64.tar.gz | tar xz

# Chain: HTTP :8081 → SOCKS5 microwarp :1080
# IMPORTANT: use socks5:// NOT socks5h:// to resolve DNS locally
nohup ./gost \
  -F "socks5://${WARP_USER}:${WARP_PASS}@127.0.0.1:1080" \
  -L "http://:8081" \
  > /dev/null 2>&1 &

⚠️ Always use socks5:// not socks5h:// — socks5h delegates DNS to the proxy, which can deadlock during WireGuard UDP handshake cold start causing 503 errors.

Multi-instance setup (different ports)

version: '3.8'

services:
  warp-1:
    image: ghcr.io/ccbkkb/microwarp:latest
    ports: ["1080:1080"]
    cap_add: [NET_ADMIN, SYS_MODULE]
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    volumes:
      - warp-data-1:/etc/wireguard

  warp-2:
    image: ghcr.io/ccbkkb/microwarp:latest
    ports: ["1081:1080"]
    cap_add: [NET_ADMIN, SYS_MODULE]
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    volumes:
      - warp-data-2:/etc/wireguard

volumes:
  warp-data-1:
  warp-data-2:

Common Integration Patterns

With Xray/V2Ray outbound

{
  "outbounds": [
    {
      "tag": "warp",
      "protocol": "socks",
      "settings": {
        "servers": [
          {
            "address": "127.0.0.1",
            "port": 1080,
            "users": [
              { "user": "admin", "pass": "yourpass" }
            ]
          }
        ]
      }
    }
  ]
}

With Telegram (via proxychains)

# /etc/proxychains4.conf
[ProxyList]
socks5 127.0.0.1 1080

proxychains4 telegram-desktop

Monitoring & Debugging

# Check container resource usage
docker stats microwarp

# Expected output:
# CONTAINER ID   NAME       CPU %   MEM USAGE / LIMIT     MEM %
# 2fa58f84c517   microwarp  0.25%   800KiB / 967.4MiB     0.08%

# View logs (first-run registration)
docker logs microwarp

# Inspect WireGuard interface inside container
docker exec microwarp wg show

# Check if SOCKS5 port is listening
docker exec microwarp ss -tlnp | grep 1080

# Test from inside container
docker exec microwarp wget -qO- --timeout=10 \
  -e "use_proxy=yes" \
  -e "https_proxy=socks5://127.0.0.1:1080" \
  https://cloudflare.com/cdn-cgi/trace

Troubleshooting

Container fails to start — missing kernel module

Error: WireGuard kernel module not found

Fix: Ensure host kernel has WireGuard support (Linux 5.6+ has it built-in):

# Check host kernel
uname -r
# Should be 5.6+

# Verify wireguard module
modprobe wireguard && echo "OK"

Add SYS_MODULE capability and the sysctl:

cap_add:
  - NET_ADMIN
  - SYS_MODULE
sysctls:
  - net.ipv4.conf.all.src_valid_mark=1

Registration fails / cannot connect to Cloudflare

Fix: Inject a known-good WARP endpoint:

environment:
  - ENDPOINT_IP=162.159.193.10:2408

Popular clean endpoints:

• 162.159.193.10:2408
• 162.159.195.1:2408
• 188.114.96.1:2408

SOCKS5 returns 503 intermittently

This is the WireGuard UDP handshake cold-start issue. Fix: Use socks5:// not socks5h:// in your client. The difference:

• socks5:// — client resolves DNS, sends IP to proxy ✅
• socks5h:// — proxy resolves DNS, hits WireGuard during cold start ❌

Volume permission issues on restart

# Check volume contents
docker run --rm -v warp-data:/data alpine ls -la /data

# If empty after accidental volume deletion, container will re-register automatically
# Just restart and wait ~10 seconds
docker compose restart microwarp

High CPU on arm64 (Oracle Cloud)

Ensure you're pulling the multi-arch image correctly:

# Force arm64 pull
docker pull --platform linux/arm64 ghcr.io/ccbkkb/microwarp:latest

Required Docker Capabilities

| Capability | Reason | |---|---| | NET_ADMIN | Create/configure wg0 WireGuard interface | | SYS_MODULE | Load WireGuard kernel module if not already loaded | | net.ipv4.conf.all.src_valid_mark=1 | Required for WireGuard routing marks |

Architecture Notes for AI Agents

• The image is ~9MB (Alpine-based)
• No warp-cli, no Rust daemon — pure kernel WireGuard + C microsocks
• Config persisted at /etc/wireguard/wg0.conf inside the volume
• First-run script auto-calls Cloudflare WARP API to register and get keypair
• SOCKS5 server binds inside container; map host port via Docker -p
• Multi-arch: linux/amd64 and linux/arm64 supported natively