Skip to main content

​
Prerequisites

Before installing APITHON, ensure your system meets these requirements:

Python 3.x

Python 3.7 or higher is required

pip Package Manager

Usually included with Python installations

Internet Connection

Required for downloading dependencies and Chromium

500MB Disk Space

For dependencies and Chromium browser

​
Verify Python Installation

Check if Python is installed and meets version requirements: 
python3 --version
# or
python --version
You should see output like: 
Python 3.11.5
If Python is not installed, download it from python.org before proceeding.

​
Installation Steps

1

Create Project Directory

Create a dedicated directory for APITHON:
mkdir apithon-project
cd apithon-project
2

Set Up Virtual Environment (Recommended)

Create an isolated Python environment to avoid dependency conflicts:
python3 -m venv venv
source venv/bin/activate
When activated, you’ll see (venv) at the beginning of your command prompt.
Virtual environments:
  • Isolate project dependencies from system Python
  • Prevent version conflicts between projects
  • Make dependencies easier to manage and reproduce
  • Allow different Python versions per project
3

Install Python Dependencies

Install the three required Python packages (README.md:41):
pip install flask playwright curl_cffi
Package Breakdown:
PackageVersionPurpose
flaskLatestWeb framework for the API gateway (apithon.py:10)
playwrightLatestBrowser automation for protocol interception (apithon.py:11)
curl_cffiLatestHTTP client with TLS fingerprinting (apithon.py:12)
The installation may take a few minutes as pip downloads and installs all dependencies and their requirements.
You should see output similar to:
Collecting flask
  Downloading flask-3.0.0-py3-none-any.whl (99 kB)
Collecting playwright
  Downloading playwright-1.40.0-py3-none-any.whl (37.3 MB)
Collecting curl_cffi
  Downloading curl_cffi-0.6.2-py3-none-any.whl
...
Successfully installed flask-3.0.0 playwright-1.40.0 curl-cffi-0.6.2 ...
4

Install Chromium Browser

Playwright requires a browser for automation. Install Chromium (README.md:42):
playwright install chromium
This downloads approximately 150-200MB. The browser is installed in Playwright’s cache directory, not your project folder.
Expected output:
Downloading Chromium 119.0.6045.9 (playwright build v1091)
142.5 MB [====================] 100% 0.0s
Chromium 119.0.6045.9 downloaded to /home/user/.cache/ms-playwright/chromium-1091
If you need Firefox or WebKit for testing:
playwright install
This installs all supported browsers (Chromium, Firefox, WebKit).
5

Download APITHON

Place the apithon.py script in your project directory.Verify the file is present:
ls -lh apithon.py
You should see the file listed (approximately 7-8 KB).
6

Verify Installation

Test that all dependencies are correctly installed:
python -c "import flask, playwright, curl_cffi; print('✓ All dependencies installed successfully')"
If successful, you’ll see:
✓ All dependencies installed successfully
If you see ModuleNotFoundError, revisit Step 3 and ensure all packages installed without errors.

​
Platform-Specific Considerations

​
Windows Installation

If you encounter errors activating the virtual environment in PowerShell:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
This allows locally created scripts to run while maintaining security for remote scripts.
Some antivirus software may flag Playwright’s browser automation. You may need to:
  • Add an exception for the Python Scripts directory
  • Add an exception for %USERPROFILE%\.cache\ms-playwright
  • Temporarily disable real-time protection during Chromium installation
Some dependencies may require Microsoft Visual C++ Redistributable:

​
Linux Installation

On some Linux distributions, you may need additional system libraries:Ubuntu/Debian:
sudo apt-get update
sudo apt-get install -y python3-pip python3-venv libssl-dev libffi-dev
Fedora/RHEL:
sudo dnf install python3-pip python3-virtualenv openssl-devel libffi-devel
Arch Linux:
sudo pacman -S python-pip python-virtualenv openssl
Playwright may require additional system libraries for Chromium:
playwright install-deps chromium
This installs system dependencies like libglib, libnss3, libatk, etc.
If you encounter permission errors:
  • Avoid using sudo pip (use virtual environment instead)
  • Ensure your user owns the project directory: sudo chown -R $USER:$USER ~/apithon-project

​
macOS Installation

macOS may require Xcode Command Line Tools:
xcode-select --install
Click “Install” in the dialog that appears.
If using Python from Homebrew:
brew install python@3.11
python3.11 -m venv venv

​
Troubleshooting

​
Common Issues and Solutions

Cause: Virtual environment not activated or packages not installed.Solution:
# Activate virtual environment
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Reinstall packages
pip install flask playwright curl_cffi
Cause: Chromium not installed or Playwright cache corrupted.Solution:
# Reinstall Chromium
playwright install chromium

# If that fails, clear cache and reinstall
rm -rf ~/.cache/ms-playwright
playwright install chromium
Cause: Missing or outdated SSL libraries.Solution (Linux):
sudo apt-get install libssl-dev  # Ubuntu/Debian
sudo dnf install openssl-devel    # Fedora/RHEL

# Reinstall curl_cffi
pip uninstall curl_cffi
pip install curl_cffi
Solution (Windows):
  • Update Windows
  • Install Visual C++ Redistributable
  • Use Python from python.org (not Microsoft Store)
Cause: Another application is using port 5000 (common with macOS AirPlay).Solution: Modify apithon.py:167 to use a different port:
app.run(host=host, port=5001, debug=False, use_reloader=False)
Or stop the conflicting service:
# macOS - disable AirPlay Receiver
sudo defaults write com.apple.AirPlayReceiverKit AirPlayReceiverEnabled -bool false
Cause: Network connectivity issues or firewall blocking.Solution:
  • Check internet connection
  • Disable VPN temporarily
  • Configure firewall to allow Chromium
  • Try a different target URL
Cause: Insufficient permissions for cache directory or network binding.Solution:
# Fix cache directory permissions
chmod -R 755 ~/.cache/ms-playwright

# For port binding < 1024, use higher port or:
sudo setcap 'cap_net_bind_service=+ep' $(which python3)

​
Debugging Tips

Enable verbose logging to diagnose issues:
export DEBUG=pw:api  # Linux/macOS
set DEBUG=pw:api     # Windows CMD
$env:DEBUG="pw:api"  # Windows PowerShell

python apithon.py
This shows detailed Playwright operation logs.

​
Getting Help

If you encounter issues not covered here:
  1. Check Python version: Ensure Python 3.7+
  2. Verify virtual environment: Confirm it’s activated
  3. Review error messages: Read the full traceback
  4. Test dependencies individually: Import each package in Python REPL
  5. Update packages: pip install --upgrade flask playwright curl_cffi

​
Verifying Successful Installation

Run this comprehensive verification: 
python apithon.py
You should see: 
┌──────────────────────────────────────────────────────────────────────────┐
│  _______  _______  ___  _______  __   __  _______  __    _               │
│ |   _   ||       ||   ||       ||  | |  ||       ||  |  | |              │
│ |  |_|  ||    _  ||   ||_     _||  |_|  ||   _   ||   |_| |              │
│ |       ||   |_| ||   |  |   |  |       ||  | |  ||       |              │
│ |       ||    ___||   |  |   |  |       ||  |_|  ||  _    |              │
│ |   _   ||   |    |   |  |   |  |   _   ||       || | |   |              │
│ |__| |__||___|    |___|  |___|  |__| |__||_______||_|  |__|              │
│                                                                          │
│  >> UNHACKERENCAPITAL | PROTOCOL ANALYSIS | GATEWAY POC v3.0 <<          │
└──────────────────────────────────────────────────────────────────────────┘
[?] Ingrese la URL del objetivo (ej: app.serviciollm.com):
If you see the ASCII art banner and the URL prompt, installation is successful!
You can press Ctrl+C to exit without entering a URL.

​
Post-Installation

For convenience, create a shell script to activate the environment and launch APITHON: 
#!/bin/bash
cd "$(dirname "$0")"
source venv/bin/activate
python apithon.py
Make it executable: 
chmod +x launch.sh  # Linux/macOS only
Now you can launch with ./launch.sh (Linux/macOS) or launch.bat (Windows).

​
Update Dependencies

Keep your installation up to date: 
pip install --upgrade flask playwright curl_cffi
playwright install chromium

​
Next Steps

Quick Start

Follow the quickstart guide to run your first protocol analysis

Introduction

Learn about APITHON’s architecture and capabilities
Installation complete! You’re ready to start analyzing protocols with APITHON.

Build docs developers (and LLMs) love

Get started for freeTalk to us