Replica is a lightweight, Python-based reverse proxy. It mirrors content from a target origin, sanitizes headers to keep downstream proxies happy, and handles on-the-fly text replacement. It includes an in-memory TTL cache for static assets and HTML to ensure high performance.
- Smart Proxying: Forward requests to any target origin with minimal overhead.
- TLS Fingerprint Impersonation: Uses curl-impersonate to match Chrome or Firefox browser fingerprints based on incoming User-Agent, bypassing anti-bot protections.
- In-Memory Caching: Built-in TTL caching for static files and HTML.
- Header Sanitization: Automatically cleans headers to prevent conflicts with Cloudflare or other edge proxies.
- Dynamic Content Rewriting: Automatically rewrites target origin URLs to your proxy origin in HTML/JS/CSS content.
- Custom Text Replacements: Perform regex-based text replacements on the fly.
- JS Injection: Easily inject custom JavaScript into the
<body>of proxied HTML pages.
The easiest way to deploy Replica is pulling the pre-built image directly from the GitHub Container Registry.
You don't need to clone the repo to run the proxy. Just create a .env file (see Configuration) and run:
docker run -d \
-p 8000:8000 \
--env-file .env \
--name replica \
ghcr.io/sarperavci/replica:latest
# or without any extra string replacement rules:
docker run -d -p 8000:8000 --env TARGET_ORIGIN="https://example.com" --name replica ghcr.io/sarperavci/replica:latestIf you prefer to build the image yourself or use Docker Compose:
# Clone the repo
git clone https://github.com/sarperavci/replica.git
cd replica
# Build and run
docker compose up --buildReplica is configured entirely via environment variables.
| Variable | Default | Description |
|---|---|---|
TARGET_ORIGIN |
https://example.com |
The upstream site you want to proxy. |
REPLACEMENTS |
[] |
JSON string of rules. Use "to": "MY_HOST" to dynamically map to your origin. |
CACHE_TTL_STATIC |
(Internal Default) | Time-to-live (seconds) for static files. |
CACHE_TTL_HTML |
(Internal Default) | Time-to-live (seconds) for HTML content. |
INJECT_JS |
None |
String of JavaScript to inject into HTML pages. |
INJECT_JS_FILE |
None |
Path to a local JS file. If set, this overrides INJECT_JS. |
INJECT_JS_LOCATION |
body |
Where to inject JS: head (before </head>) or body (before </body>). |
Follow these steps to set up a local environment for debugging or contributing.
# Create a virtual environment
python3.10 -m venv .venv
# Activate it
source .venv/bin/activate
# Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtCreate a .env file in the root directory:
cp .env.example .envEnsure the variables (especially TARGET_ORIGIN) are set correctly for your local testing.
Run the server with Uvicorn:
uvicorn replica.main:app --host 0.0.0.0 --port 8000Development Mode (Hot Reload):
For active development, use the --reload flag to automatically reload on code changes:
uvicorn replica.main:app --reload --host 127.0.0.1 --port 8000- Google.com mirroring not supported: Google employs advanced bot detection and requires specific handling that is not currently implemented.
- WebSocket connections not supported: The proxy only handles HTTP/HTTPS requests. Real-time WebSocket connections are not proxied and will fail.
MIT License. See LICENSE for details.
Pull requests are welcome. If you find a bug or want to suggest a feature, please open an issue.