Certificate Setup

APXY uses a root CA certificate to intercept HTTPS traffic (MITM). The CA must be trusted by your system for SSL interception to work without errors.

Web UI

The Setup Center page shows a live readiness checklist including certificate status. It displays whether the CA certificate has been generated and trusted, and provides diagnostic information if something is misconfigured.

macOS (Automatic)

On macOS, apxy start handles everything automatically:

1. Generates the CA certificate on first run
2. Prompts for your password to trust the CA in the system keychain
3. All subsequent runs skip this step

If you need to manually manage certificates:

# Generate root CA
apxy certs generate
 
# View CA info
apxy certs info
 
# Trust CA in macOS Keychain (requires sudo)
sudo apxy certs trust

Regenerate certificates

If you’re getting SSL errors, try regenerating:

rm -rf certs/
apxy start
# macOS will prompt for your password to trust the new CA

Linux

On Linux, the proxy does not configure the system proxy or trust the CA automatically. Manual setup is required.

Trust the CA (Ubuntu/Debian)

sudo cp certs/ca.crt /usr/local/share/ca-certificates/apxy-ca.crt
sudo update-ca-certificates

Trust the CA (RHEL/CentOS/Fedora)

sudo cp certs/ca.crt /etc/pki/ca-trust/source/anchors/apxy-ca.crt
sudo update-ca-trust

Per-tool CA trust

Some tools don’t use the system certificate store. Pass the CA certificate directly:

# cURL
curl --cacert ~/.apxy/certs/ca.crt https://example.com
 
# Node.js
export NODE_EXTRA_CA_CERTS=~/.apxy/certs/ca.crt
 
# Python (requests)
export REQUESTS_CA_BUNDLE=~/.apxy/certs/ca.crt

HTTPS Interception Modes

APXY supports three levels of HTTPS interception:

HTTPS MITM is opt-in by default for privacy. Enable deep inspection per domain:

apxy ssl enable --domain api.example.com

See SSL Proxying for more details.