Table of Contents

• Features
• Install
• Using PIP
  • Stable version
  • Development version
• Using Docker
  • Stable version from Docker Hub
  • Development Version from GHCR
  • Build container locally
• Using HomeBrew
  • Stable version
  • Development version
• Start proxy.py
• From command line when installed using PIP
  • Run it
  • Understanding logs
  • Enable DEBUG logging
• From command line using repo source
• Docker Image
  • Customize Startup Flags
• Plugin Examples
• HTTP Proxy Plugins
  • ShortLink Plugin
  • Modify Post Data Plugin
  • Mock Api Plugin
  • Redirect To Custom Server Plugin
  • Filter By Upstream Host Plugin
  • Cache Responses Plugin
  • Cache By Response Type
  • Man-In-The-Middle Plugin
  • Proxy Pool Plugin
  • Filter By Client IP Plugin
  • Modify Chunk Response Plugin
  • Modify Request Header Plugin
  • Cloudflare DNS Resolver Plugin
  • Custom DNS Resolver Plugin
  • Custom Network Interface
  • Program Name Plugin
• HTTP Web Server Plugins
  • Web Server Route
• Reverse Proxy Plugins
  • Reverse Proxy
• Plugin Ordering
• End-to-End Encryption
• TLS Interception
• Insecure TLS Interception
• TLS Interception With Docker
• GROUT (NGROK Alternative)
• Grout Usage
• Grout Authentication
• Grout Paths
• Grout Wildcard Domains
• "Host" Header Based Wildcard Routing
• "Dynamic" Routing
• Grout using Docker
• How Grout works
• Self-hosted Grout
• Proxy Over SSH Tunnel
• Proxy Remote Requests Locally
• Proxy Local Requests Remotely
• Embed proxy.py
• Blocking Mode
• Non-blocking Mode
• Ephemeral Port
• Loading Plugins
• Unit testing with proxy.py
• proxy.TestCase
• Override Startup Flags
• With unittest.TestCase
• Utilities
• TCP
  • new_socket_connection
  • socket_connection
• Http
  • build_http_request
  • build_http_response
• Public Key Infrastructure
  • API Usage
  • CLI Usage
• Run Dashboard
• Inspect Traffic
• Chrome DevTools Protocol
• Prometheus Metrics
• Frequently Asked Questions
• Deploying proxy.py in production
  • What not to do?
  • Via Requirements
  • Via Docker Container
  • Integrate your CI/CD with proxy.py
• Stable vs Develop
  • Release Schedule
• Threads vs Threadless
• Threadless Remote vs Local Execution Mode
• SyntaxError: invalid syntax
• Unable to load plugins
• Unable to connect with proxy.py from remote host
• Basic auth not working with a browser
• Docker image not working on MacOS
• ValueError: filedescriptor out of range in select
• None:None in access logs
• OSError when wrapping client for TLS Interception
• Plugin Developer and Contributor Guide
• High level architecture
• Everything is a plugin
• Managing states for your stateless plugins
• Passing processing context between plugins
• Internal Documentation
  • Read The Doc
  • pydoc
  • pyreverse
• Development Guide
  • Setup Local Environment
  • Setup Git Hooks
  • Sending a Pull Request
• Projects Using Proxy.Py
• Benchmarks
• Flags
• Changelog
• v2.x
• v1.x
• v0.x

Features

• A drop-in alternative to ngrok

• Fast & Scalable

• Scale up by using all available cores on the system

• Threadless executions using asyncio

• Made to handle tens-of-thousands connections / sec

  ```console

  On Macbook Pro M2 2022

  ❯ python --version Python 3.11.8 ❯ oha --version oha 1.4.3 ❯ ./benchmark/compare.sh CONCURRENCY: 100 workers, DURATION: 1m, TIMEOUT: 1sec ============================= Benchmarking Proxy.Py Server (pid:75969) running Summary: Success rate: 100.00% Total: 60.0006 secs Slowest: 0.2525 secs Fastest: 0.0002 secs Average: 0.0019 secs Requests/sec: 51667.3774

  Total data:   56.17 MiB
  Size/request: 19 B
  Size/sec:     958.64 KiB
  

  Response time histogram: 0.000 [1] | 0.025 [3073746] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 0.051 [10559] | 0.076 [4980] | 0.101 [2029] | 0.126 [5896] | 0.152 [2466] | 0.177 [116] | 0.202 [40] | 0.227 [52] | 0.253 [87] |

  Response time distribution: 10.00% in 0.0005 secs 25.00% in 0.0007 secs 50.00% in 0.0009 secs 75.00% in 0.0014 secs 90.00% in 0.0021 secs 95.00% in 0.0035 secs 99.00% in 0.0198 secs 99.90% in 0.1262 secs 99.99% in 0.1479 secs

  Details (average, fastest, slowest): DNS+dialup: 0.0018 secs, 0.0004 secs, 0.0031 secs DNS-lookup: 0.0000 secs, 0.0000 secs, 0.0002 secs

  Status code distribution: [200] 3099972 responses

  Error distribution: [100] aborted due to deadline ============================= ```

  Consult Threads vs Threadless and Threadless Remote vs Local Execution Mode to control number of CPU cores utilized.

  See Benchmark for more details and for how to run benchmarks locally.

• Lightweight

• Uses only ~5-20 MB RAM
  • No memory leaks
  • Start once and forget, no restarts required
• Compressed containers size is only ~25 MB

• No external dependency other than standard Python library

• Programmable

• Customize proxy behavior using Proxy Server Plugins. Example:
  • --plugins proxy.plugin.ProxyPoolPlugin
• Enable builtin Web Server. Example:
  • --enable-web-server --plugins proxy.plugin.WebServerPlugin
• Enable builtin Reverse Proxy Server. Example:
  • --enable-reverse-proxy --plugins proxy.plugin.ReverseProxyPlugin

• Plugin API is currently in development phase. Expect breaking changes. See Deploying proxy.py in production on how to ensure reliability across code changes.

• Can listen on multiple addresses and ports

• Use --hostnames flag to provide additional addresses
• Use --ports flag to provide additional ports
• Optionally, use --port flag to override default port 8899

• Capable of serving multiple protocols over the same port

• Real-time Dashboard

• Optionally, enable proxy.py dashboard.
  • Use --enable-dashboard
  • Then, visit http://localhost:8899/dashboard
• Inspect, Monitor, Control and Configure proxy.py at runtime
• Chrome DevTools Protocol support
• Extend dashboard frontend using typescript based plugins

• Dashboard is currently in development phase Expect breaking changes.

• Secure

• Enable end-to-end encryption between clients and proxy.py

• See End-to-End Encryption

• Private

• Protection against DNS based traffic blockers
• Browse with malware and adult content protection enabled
• See [DNS-over-HTTPS](#cloudflarednsresolve