HTTP Proxy CLI
A lightweight HTTP proxy CLI tool that intercepts and logs all requests to/from a specific target site.
Features
- ✅ Command-line interface with rich argument support
- ✅ Intercepts all HTTP methods (GET, POST, PUT, DELETE, etc.)
- ✅ Complete logging of requests and responses
- ✅ Configurable output formats (JSON or plain text)
- ✅ Flexible logging levels and file locations
- ✅ Real-time statistics and testing tools
Quick Start
Installation
Option 1: Install as package (recommended)
cd agent-proxy
pip install -e .
# Now you can import as:
# from agent_proxy.proxy import SimpleProxy
# from agent_proxy.logger import ProxyLogger
Option 2: Install dependencies only
cd agent-proxy
pip install -r requirements.txt
# You can run the CLI as a module, but imports must use the agent_proxy prefix.
Note: CLI scripts (http-proxy, proxy-stats, proxy-test) are available when installing the package (pip install -e .) or when running via Poetry (poetry run ...).
Using Poetry (alternative):
cd agent-proxy
poetry install
# run CLI via Poetry
poetry run http-proxy --help
# import in Python as:
# from agent_proxy.proxy import SimpleProxy
# from agent_proxy.logger import ProxyLogger
CLI Usage
Basic usage:
# Start proxy with default settings
http-proxy --target https://api.example.com
# Custom port and host
http-proxy --target https://httpbin.org --port 8080 --host 0.0.0.0
# Custom logging
http-proxy --target https://jsonplaceholder.typicode.com \
--log-file my_logs.json \
--log-level DEBUG \
--log-format json
CLI Commands
Main proxy command:
http-proxy --target https://api.example.com [OPTIONS]
Show statistics:
proxy-stats --log-file proxy_requests.log
Test target connectivity:
proxy-test --target https://api.example.com --path /health
CLI Arguments
| Argument | Short | Default | Description |
|---|---|---|---|
--target |
-t |
required | Target URL to proxy requests to |
--host |
-h |
127.0.0.1 |
Host to bind the proxy server to |
--port |
-p |
8000 |
Port to bind the proxy server to |
--log-file |
-l |
logs/proxy_requests.log |
Log file path (default folder: logs/) |
--log-level |
-v |
INFO |
Logging level (DEBUG, INFO, WARNING, ERROR) |
--log-format |
-f |
json |
Log format (json or plain) |
--no-console |
False |
Disable console logging output | |
--reload |
False |
Enable auto-reload for development | |
--workers |
-w |
1 |
Number of worker processes |
Examples
Basic proxy setup:
# Proxy to httpbin.org on port 8080
http-proxy --target https://httpbin.org --port 8080
# Test with curl
curl http://localhost:8080/get
curl -X POST http://localhost:8080/post -d '{"test": "data"}'
Advanced logging:
# Debug mode with plain text logs
http-proxy --target https://api.github.com \
--log-level DEBUG \
--log-format plain \
--log-file github_logs.txt
# Quiet mode (no console output)
http-proxy --target https://api.example.com --no-console
Production setup:
# Bind to all interfaces with multiple workers
http-proxy --target https://api.example.com \
--host 0.0.0.0 \
--port 80 \
--workers 4 \
--log-level WARNING
Testing and Statistics
Check proxy statistics:
# Show basic stats
proxy-stats
# Custom log file
proxy-stats --log-file custom_logs.json
Test target connectivity:
# Basic connectivity test
proxy-test --target https://api.example.com
# Test specific endpoint
proxy-test --target https://api.example.com --path /health
Log Format
JSON format (default):
{
"type": "request",
"request_id": "req_1234567890",
"timestamp": "2024-01-15T10:30:00.123456",
"method": "POST",
"url": "https://api.example.com/users",
"headers": {
"content-type": "application/json",
"authorization": "Bearer token123"
},
"body": "{\"name\": \"John\", \"email\": \"john@example.com\"}",
"size": 45
}
Plain text format:
2024-01-15 10:30:00 - INFO - REQUEST [req_1234567890] POST https://api.example.com/users - Headers: 5 - Body: 45 bytes
Python Module Usage
Direct usage:
from agent_proxy.proxy import SimpleProxy
from agent_proxy.logger import ProxyLogger
# Create custom logger
logger = ProxyLogger(log_file="custom.log", log_format="json")
# Create proxy
proxy = SimpleProxy("https://api.example.com", logger)
app = proxy.create_app()
# Run with uvicorn
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
Development
Install in development mode:
pip install -e .
Run tests:
# Using CLI scripts (after install):
http-proxy --help
proxy-stats --help
proxy-test --help
# Or as a module (if not installed):
python -m agent_proxy.cli --help
python -m agent_proxy.cli --target https://httpbin.org --port 8080
Package structure
Your package now uses the following structure for importable modules:
src/
agent_proxy/
__init__.py
cli.py
logger.py
proxy.py
Log Files
proxy_requests.log: Detailed request/response logs- Console output: Real-time request tracking
Error Handling
The CLI handles common errors gracefully:
- Invalid URLs: Validates target URLs start with http:// or https://
- Connection errors: Returns appropriate HTTP status codes
- Timeout handling: 30s default timeout with proper error responses
- Port conflicts: Clear error messages for port binding issues
Metadata
Release files for agent-proxy 0.2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_proxy-0.2.4.tar.gz | 6.9 kB | Without provenance | Details for agent_proxy-0.2.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_proxy-0.2.4-py3-none-any.whl | Python 3 | none | any | Details for agent_proxy-0.2.4-py3-none-any.whl |
Total release size: 15.8 kB
Release files / agent_proxy-0.2.4.tar.gz
| Download URL | agent_proxy-0.2.4.tar.gz |
|---|---|
| Size | 6.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5243492b357ad848a17d5e1d93fe4e59937514752b74f3b0e97a6efdfabb3602
|
|
BLAKE2b-256 checksum How to use checksums |
88f6a4da09e20dd3c3bfa78d59045668712e96abf905750090ecabfc4bea5995
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.4 CPython/3.13.5 Darwin/24.6.0
|
Release files / agent_proxy-0.2.4-py3-none-any.whl
| Download URL | agent_proxy-0.2.4-py3-none-any.whl |
|---|---|
| Size | 8.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f32d67b4f2434851326031042d47541a0775e5f41ef0f6e99dbe60895132b6b6
|
|
BLAKE2b-256 checksum How to use checksums |
7bde12a432e932be611e6b862d09c1b34bb9b109c17b7dfa32bda541e506c6d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.4 CPython/3.13.5 Darwin/24.6.0
|
Security for agent-proxy 0.2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.