🦊 FoxCloud - Edge Proxy for Cloudflare Workers

FoxCloud is a high-performance VLESS proxy server built for Cloudflare Workers, designed to provide secure and fast internet access through Cloudflare's global network.

📚 Documentation

• API Documentation - Endpoint reference and usage
• Architecture - System design and components
• Best Practices - Security, performance, and maintenance guidelines
• Cloudflare Limits - Worker limits and quotas
• Deployment Guide - Complete instructions for all deployment methods
• Environment Variables - How to configure UUIDs and proxy IPs
• FAQ - Frequently asked questions
• Project Structure - Directory organization and file layout
• Subscription Guide - Using the subscription system with clients
• Testing Guide - How to test the application
• Troubleshooting Guide - Solutions to common issues
• Upgrading Guide - How to upgrade your deployment
• Contributing Guide - How to contribute to the project

✨ Features

• Lightning Fast: Powered by Cloudflare's global network with 200+ data centers
• Secure: Enterprise-grade encryption with TLS 1.3 support
• Easy Deployment: One-click deploy to Cloudflare Workers
• Multi-Protocol: VLESS support with WebSocket transport
• Subscription Management: Automatic configuration generation

🚀 Quick Start

Method 1: Download Pre-built Worker (Recommended)

1. Download the latest worker.js from Releases
2. Deploy to Cloudflare Workers:

   npm install -g wrangler
   wrangler deploy worker.js

Method 2: Build from Source

# Clone the repository
git clone https://github.com/code3-dev/foxcloud.git
cd foxcloud

# Install dependencies
npm install

# Configure environment variables
# Copy example configuration and edit:
cp wrangler.example.toml wrangler.toml
# Edit wrangler.toml with your UUIDs and proxy IPs

# Build the project
npm run build

# Deploy to Cloudflare Workers
npm run deploy

Method 3: GitHub Actions (CI/CD)

1. Fork this repository
2. Set up Cloudflare credentials in repository secrets:
   • CLOUDFLARE_API_TOKEN
   • CLOUDFLARE_ACCOUNT_ID
3. Enable GitHub Actions in repository settings
4. Push to master branch to trigger automatic deployment

⚙️ Environment Variables

FoxCloud requires the following environment variables to be configured in your Cloudflare Worker:

Variable	Description	Example
UUID	Comma-separated list of user UUIDs	08dad8a6-8a6c-4424-9d63-62f3a9bf7f4f,49d598ee-4dfc-4001-95ca-99a5b6002e3c
PROXY_IP	Comma-separated list of proxy IPs with ports	172.66.45.9:443,104.18.128.25:443,162.159.136.94:443

See the Environment Variables Guide for detailed instructions on:

• Generating secure UUIDs
• Validating proxy IPs
• Setting variables via different methods
• Security best practices
• Troubleshooting common issues

See the Status Page Template for information on implementing a public status page.

🛠️ Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Deploy to Cloudflare
npm run deploy

🔧 Configuration

Customizing UUIDs

Generate secure UUIDs using:

# On Linux/macOS
cat /proc/sys/kernel/random/uuid

# On Windows PowerShell
New-Guid

# Using Node.js
node -e "console.log(require('crypto').randomUUID())"

# Using FoxCloud helper script
npm run generate-uuid

See the scripts directory for additional utility scripts.

Proxy IPs

FoxCloud supports multiple proxy IPs for load balancing. Add multiple IPs separated by commas:

PROXY_IP = "172.66.45.9:443,104.18.128.25:443,162.159.136.94:443"

📱 Client Configuration

After deployment, access your subscription configuration at:

https://your-worker.your-subdomain.workers.dev/sub

See the Subscription Guide for detailed instructions on:

• Configuring V2Ray compatible clients
• Setting up mobile clients
• Managing multiple UUIDs
• Troubleshooting connection issues

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Cloudflare Workers for the amazing platform
• VLESS Protocol for secure proxy technology
• All contributors who have helped shape FoxCloud

---

Made with 🦊 by the Hossein Pira & IRCF