Mitmproxy Deployment and Usage Guide

Prerequisites

Python 3.8 or later (required for mitmproxy)
Operating System: Linux, macOS, or Windows
Optional for development: Git for cloning the repository
Network access: Required for package installation and proxying traffic

Installation

Option 1: Install via pip (Recommended)

pip install mitmproxy

Option 2: Install from source

Clone the repository:

git clone https://github.com/mitmproxy/mitmproxy.git
cd mitmproxy

Install dependencies and build:

pip install -e .

Option 3: Install precompiled binaries

Download precompiled binaries from the official website:

mitmproxy.org

Configuration

Environment Variables

Mitmproxy uses the following environment variables:

MITMPROXY_CONFIG: Path to custom configuration file
MITMPROXY_HOME: Directory for mitmproxy data (default: ~/.mitmproxy)

Configuration Files

Mitmproxy automatically creates a configuration directory at ~/.mitmproxy on first run. You can customize settings in:

~/.mitmproxy/config.yaml - Main configuration file
~/.mitmproxy/addons/ - Directory for custom addons

SSL/TLS Certificates

Mitmproxy generates its own CA certificate on first use. You'll need to:

Install the mitmproxy CA certificate in your system/browser trust store
For mobile devices, configure the proxy settings to use your machine's IP and port 8080

Build & Run

Running the Tools

Mitmproxy provides three main tools:

1. Interactive Console (mitmproxy)

mitmproxy

2. Command Line (mitmdump)

mitmdump -w outfile.mitm

3. Web Interface (mitmweb)

mitmweb

Common Usage Examples

# Start mitmproxy on a specific port
mitmproxy -p 8081

# Save flows to a file
mitmproxy -w capture.mitm

# Replay saved flows
mitmdump -n -r capture.mitm

# Transparent proxy mode
mitmproxy --mode transparent

Development Mode

For development, use the editable install:

pip install -e .

Then run the tools from the source directory:

python -m mitmproxy

Deployment

Local Development

Mitmproxy is designed to run locally on your development machine. No special deployment is needed.

Production/Server Deployment

For production use cases:

Docker Container:

FROM python:3.9-slim
RUN pip install mitmproxy
EXPOSE 8080
CMD ["mitmproxy", "-p", "8080"]

Systemd Service (Linux):

[Unit]
Description=Mitmproxy Service
After=network.target

[Service]
Type=simple
User=mitmproxy
ExecStart=/usr/local/bin/mitmproxy -p 8080
Restart=always

[Install]
WantedBy=multi-user.target

Platform Recommendations

Local Development: Direct installation on your OS
Server Deployment: Docker containers or systemd services
Cloud Deployment: Any cloud provider supporting Python applications

Troubleshooting

Common Issues and Solutions

1. SSL/TLS Certificate Errors

Problem: Browser shows "Your connection is not private" warnings Solution: Install the mitmproxy CA certificate in your trust store

# View the certificate
mitmproxy --show-ca-cert

# Install the certificate (varies by OS)
# macOS: Double-click the certificate and add to Keychain
# Windows: Right-click and install

2. Port Already in Use

Problem: "OSError: [Errno 98] Address already in use" Solution: Use a different port or kill the existing process

# Use a different port
mitmproxy -p 8081

# Find and kill the process
lsof -i :8080
kill -9 <PID>

3. Permission Denied on Port 80/443

Problem: "PermissionError: [Errno 13] Permission denied" Solution: Use ports above 1024 or run with elevated privileges

# Use elevated port
sudo mitmproxy -p 80

# Better: Use a higher port
mitmproxy -p 8080

4. Connection Refused

Problem: Cannot connect to the proxy Solution: Check firewall settings and proxy configuration

# Check if mitmproxy is running
ps aux | grep mitmproxy

# Check firewall
sudo ufw status

5. Missing Dependencies

Problem: ImportError: No module named 'mitmproxy' Solution: Ensure mitmproxy is installed in your Python environment

# Check installation
pip show mitmproxy

# Reinstall if necessary
pip install --force-reinstall mitmproxy

Getting Help

Documentation: docs.mitmproxy.org
GitHub Discussions: github.com/mitmproxy/mitmproxy/discussions
Issue Tracker: github.com/mitmproxy/mitmproxy/issues

How to Deploy & Use mitmproxy/mitmproxy