AWS Fargate SOCKS5 Proxy

Ephemeral proxy infrastructure — pay only when you need it

A production-ready, cost-effective solution for routing traffic through a different IP using AWS Fargate and SOCKS5. Ideal for geo-testing websites, avoiding geolocation restrictions, and privacy-focused browsing.

Requirements: AWS account, Docker locally. Not tested on Windows.

Main point of difference: requires almost no user input other than starting and stopping the service. Transparently handles remote proxy IP address changes when used with a tool like foxyproxy. When starting a new proxy service fargate will create a new public IP address. the choices are to update your foxyproxy config on every start, pay for a fixed IP address, or use this application which handles it in the background. It even handles local and remote IP changes midstream.

This is not a VPN Which is to say using a tool like foxyproxy you can create per website proxying rules.

Key Stats:

• Cost: ~$1–3/month (100–200 hrs)
• Setup: ~5 minutes (automated)
• Startup: 30–60 seconds
• Idle shutdown: Configurable (ephemeral — auto-saves costs)
• Persistent connections: WebSocket, SSE, HTTP/2
• Security: IP allowlist and/or username/password authentication

---

Quick Start

chmod +x setup.sh
./setup.sh                          # Automated deployment (asks about security, timeout)
./proxy-manage.sh start             # Start proxy
curl -x http://localhost:8080 http://httpbin.org/ip  # Test it

See QUICKSTART.md for step-by-step, or DEPLOYMENT.md for manual control.

---

Architecture

Your Browser (localhost:8080)
         ↓
Local HTTP Proxy (Node.js) — async-proxy/proxy.js
  ─ Monitors orchestrator for endpoint updates
  ─ Routes traffic via SOCKS5 to Fargate task
         ↓
Local Orchestrator (Python) — proxy-orchestrator/orchestrator.py
  ─ Manages Fargate task lifecycle
  ─ Detects IP changes, manages security groups
  ─ Provides management API on port 5000
         ↓
AWS Fargate SOCKS5 Proxy (serjs/go-socks5-proxy)
  ─ Ephemeral task with public IP
  ─ Optional username/password auth
  ─ Auto-stops after configured idle timeout
         ↓
Internet (with your AWS region's IP)

Browser always connects to localhost:8080 — no reconfiguration needed between sessions.

---

Daily Usage

./proxy-manage.sh start              # Start (waits ~30–60s for Fargate init)
./proxy-manage.sh stop               # Stop local proxy (Fargate auto-shuts down)
./proxy-manage.sh stop --remote      # Stop local proxy + stop Fargate task immediately
./proxy-manage.sh status             # Current status & IP
./proxy-manage.sh health             # Connectivity test
./proxy-manage.sh logs               # View logs
./proxy-manage.sh info               # Cost/config summary

Browser config: Set HTTP & HTTPS proxy to localhost:8080.

---

Security

The proxy supports two complementary security layers, configured during setup.sh:

Layer	When to use	How it works
IP Allowlist	Office/static IP	Security group restricts port 1080 to your IP only. Auto-detects IP changes.
Username/Password	Dynamic IP / extra protection	SOCKS5 authentication via PROXY_USER/PROXY_PASSWORD. Required when IP allowlist is off.

• If IP allowlist is enabled: auth is optional (recommended for defense-in-depth)
• If IP allowlist is disabled: auth is mandatory — setup.sh enforces this

See SECURITY-IP-ALLOWLIST.md for details.

---

Configuration

All configuration is stored in .env (generated by setup.sh). Key values:

Variable	Default	Description
TASK_IDLE_TIMEOUT_MINUTES	60	Fargate auto-shutdown after N min idle (0 = disabled)
IP_ALLOWLIST_ENABLED	false	Restrict proxy to your public IP
REQUIRE_AUTH	false	Require SOCKS5 username/password
PROXY_USER	—	SOCKS5 username
PROXY_PASSWORD	—	SOCKS5 password
DUAL_IP_RETENTION_MINUTES	180	Keep old IP in SG when IP changes

---

Costs

Usage	Monthly Cost
50 hrs	~$0.60
100 hrs	~$1.20
200 hrs	~$2.40

Includes: Fargate compute (vCPU+memory), 1 GB data transfer, auto-shutdown Lambda, CloudWatch logs. Savings: Ephemeral by design — no minimum, pay only when running, auto-shutdown after idle timeout.

---

File Guide

File	Purpose
QUICKSTART.md	5-min quick start
README.md	Full documentation reference (this file)
DEPLOYMENT.md	Step-by-step deployment & troubleshooting
fargate-proxy-architecture.md	Architecture deep-dive
SECURITY-IP-ALLOWLIST.md	IP allowlist & auth security details
setup.sh	Automated deployment script
proxy-manage.sh	CLI management (start/stop/status/logs/info)
fargate-infrastructure.yaml	AWS CloudFormation template
docker-compose.yml	Docker Compose config for local services
async-proxy/proxy.js	Local Node.js HTTP → SOCKS5 proxy
proxy-orchestrator/orchestrator.py	Python orchestrator managing Fargate lifecycle
proxy-orchestrator/entrypoint.sh	Orchestrator container entrypoint
async-proxy/Dockerfile	Dockerfile for the local HTTP proxy
proxy-orchestrator/Dockerfile	Dockerfile for the orchestrator

Legacy: ec2-proxy-setup.md (EC2-based alternative, different approach)

---

FAQ

Do I need to update browser settings each time?
No — localhost:8080 is permanent.

Why is first startup slow?
Fargate initializes in ~30–60 seconds.

What if I forget to stop it?
Ephemeral by design — auto-shutdown after the configured idle timeout (default 60 min). If you put your PC to sleep the timer initiates, however if the local containers are still running the remote proxy will remain active, don't do that!

Can I use this remotely?
Designed for local use only. See DEPLOYMENT.md for options.

How is security handled?
Two complementary layers: IP allowlist (security group restriction) and/or SOCKS5 username/password authentication. Encrypted end-to-end.

What IP/country will I get?
Depends on the AWS region you deploy to.

Can I customize the SOCKS5 proxy?
Yes — see serjs/go-socks5-proxy for config options.

---

Troubleshooting

Symptom	Check
Proxy won't start	docker compose logs, aws sts get-caller-identity
Fargate task won't init	aws ecs list-tasks --cluster proxy-cluster, check CloudWatch logs & security groups
Can't connect	curl http://localhost:8080, verify browser proxy is localhost:8080, docker compose ps
Auth errors	Verify PROXY_USER/PROXY_PASSWORD match between .env and Fargate task definition

See DEPLOYMENT.md for detailed troubleshooting.

---

Start Here

cat QUICKSTART.md          # Read quick start (5 min)
chmod +x setup.sh          #
./setup.sh                 # Run automated setup (5 min)
chmod +x proxy-manage.sh  #
./proxy-manage.sh start    # Start proxy
curl -x http://localhost:8080 http://httpbin.org/ip   # Test

You'll have a proxy running with an IP from your chosen AWS region in ~15 minutes total.