Client setup for tools and runtimes

Apps that follow the macOS proxy setting are captured as soon as capture runs with Set as the macOS system proxy on. Command line tools, language runtimes, containers and some frameworks ignore that setting, keep their own list of trusted certificates, or both. This page gets each of them into WireLens with certificate checks left on.

Tools ▸ Client Setup in the app has every recipe below with the real paths for your Mac filled in, plus Next.js, Postman, Insomnia, Paw / RapidAPI, Firefox, Xcode Previews and Android. Runtime lists the ones detected on this Mac first. Each recipe has a Snippet to copy and a Then check it worked command with Run Now.

Quick start at the top opens a shell with the proxy and certificate already set: Open Preconfigured Terminal, Open iTerm2 with Proxy or Open Ghostty with Proxy. None of them change the macOS system proxy, and closing the window drops the variables. AirDrop Certificate… sends the certificate to an iPhone or iPad.

The two values every client needs#

• Proxy: http://127.0.0.1:9090. Check Settings ▸ Capture ▸ Listen port if you changed it.
• Certificate: your WireLens root as a PEM file, at ~/Library/Application Support/WireLens/ca/wirelens-root.pem.

wirelens ships inside the app and is not on your PATH until you link it once.

The examples below use them through two shell variables:

export WL_PROXY=http://127.0.0.1:9090
export WL_CA="$HOME/Library/Application Support/WireLens/ca/wirelens-root.pem"

curl and HTTPie#

curl --proxy "$WL_PROXY" --cacert "$WL_CA" https://example.com

# HTTPie takes scheme:host:port for --proxy
http --proxy=http:"$WL_PROXY" --verify="$WL_CA" https://example.com

# or for the whole shell session
export HTTPS_PROXY="$WL_PROXY" HTTP_PROXY="$WL_PROXY" CURL_CA_BUNDLE="$WL_CA"

Node.js#

export NODE_EXTRA_CA_CERTS="$WL_CA"
export HTTPS_PROXY="$WL_PROXY" HTTP_PROXY="$WL_PROXY"
node app.js

NODE_EXTRA_CA_CERTS adds the WireLens certificate to the ones Node already trusts. Node's own http and https modules ignore proxy variables; axios, got and node-fetch with an agent read them, and the built-in fetch needs a ProxyAgent.

Python#

export SSL_CERT_FILE="$WL_CA" REQUESTS_CA_BUNDLE="$WL_CA"
export HTTPS_PROXY="$WL_PROXY" HTTP_PROXY="$WL_PROXY"
python3 app.py

requests reads REQUESTS_CA_BUNDLE; httpx, urllib and aiohttp read SSL_CERT_FILE. aiohttp ignores the proxy variables unless you create the session with aiohttp.ClientSession(trust_env=True) or pass proxy= on each request.

Ruby#

export SSL_CERT_FILE="$WL_CA"
export https_proxy="$WL_PROXY" http_proxy="$WL_PROXY"
ruby app.rb

Go#

export HTTPS_PROXY="$WL_PROXY" HTTP_PROXY="$WL_PROXY"
go run .

On macOS, Go checks certificates against the keychain and ignores SSL_CERT_FILE. The trust the Setup Assistant sets up covers Go. Otherwise trust the certificate with Settings ▸ Certificate ▸ Trust for this user only ▸ Install… or wirelens cert install, or load the PEM in code.

Rust#

export HTTPS_PROXY="$WL_PROXY" ALL_PROXY="$WL_PROXY" SSL_CERT_FILE="$WL_CA"
cargo run

SSL_CERT_FILE covers the OpenSSL and native-tls backends. With rustls, add the certificate in code, which also works everywhere else:

let pem = std::fs::read(ca_path)?;
let client = reqwest::Client::builder()
    .proxy(reqwest::Proxy::all("http://127.0.0.1:9090")?)
    .add_root_certificate(reqwest::Certificate::from_pem(&pem)?)
    .build()?;

Java and the JVM#

The JVM keeps its own list of certificates. Copy it, add the WireLens one to the copy, then point the JVM at it:

TS="$HOME/Library/Application Support/WireLens/java-truststore/cacerts"
mkdir -p "$(dirname "$TS")"
cp "$JAVA_HOME/lib/security/cacerts" "$TS"
keytool -importcert -noprompt -trustcacerts -alias wirelens \
  -file "$WL_CA" -keystore "$TS" -storepass changeit

java -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=9090 \
     -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=9090 \
     -Djavax.net.ssl.trustStore="$TS" \
     -Djavax.net.ssl.trustStorePassword=changeit \
     -jar your-app.jar

changeit is the JDK's own default password, not a placeholder. Tools ▸ Client Setup ▸ Import CA with keytool runs the import for you.

PHP#

export HTTPS_PROXY="$WL_PROXY" HTTP_PROXY="$WL_PROXY"
php -d curl.cainfo="$WL_CA" -d openssl.cafile="$WL_CA" your-script.php

PHP does not use the macOS keychain. Set both options: file_get_contents reads openssl.cafile and ignores curl.cainfo. With Guzzle you can pass 'proxy' and 'verify' per client instead.

.NET#

export HTTPS_PROXY="$WL_PROXY" HTTP_PROXY="$WL_PROXY" NO_PROXY=localhost,127.0.0.1
dotnet run

On macOS, .NET checks against the system list. Trust the certificate in the keychain, as with Go. In a Linux container it reads SSL_CERT_FILE instead. A handler that sets Proxy in code ignores the environment: set one or the other.

Docker#

Inside a container, localhost is the container. Your Mac is host.docker.internal:

docker run --rm \
  -e HTTPS_PROXY=http://host.docker.internal:9090 \
  -e HTTP_PROXY=http://host.docker.internal:9090 \
  -e NO_PROXY=localhost,127.0.0.1 \
  -v "$WL_CA":/usr/local/share/ca-certificates/wirelens.crt:ro \
  your-image sh -c "update-ca-certificates && your-command"

In Compose, add the same environment and volume, plus extra_hosts: ["host.docker.internal:host-gateway"] if you also run it on Linux. Alpine images need the ca-certificates package before update-ca-certificates exists.

Electron#

export NODE_EXTRA_CA_CERTS="$WL_CA"
electron . --proxy-server=127.0.0.1:9090

The main process is Node, which NODE_EXTRA_CA_CERTS covers. The windows use Chromium, which takes --proxy-server and trusts certificates from the keychain. Trust the WireLens certificate there too. Tools ▸ Client Setup ▸ Launch Electron starts Electron with both set.

React Native and Flutter#

• iOS Simulator uses your Mac's network, and capture already covers it. Install the certificate into the simulator with Tools ▸ iOS Simulators, or xcrun simctl keychain booted add-root-cert "$WL_CA". See Capture other devices.
• Android emulator: your Mac is 10.0.2.2, and app traffic on Android 7 and later needs a debug network security config. The React Native recipe also has the adb reverse command Metro needs for port 8081. See Capture other devices.
• Flutter: Dart's HttpClient does not read proxy variables. Set findProxy to PROXY 127.0.0.1:9090 and add the certificate with SecurityContext.setTrustedCertificates, or install a debug HttpOverrides.global. Tools ▸ Client Setup ▸ Copy Dart override puts one on the clipboard.

Firefox#

Firefox keeps its own list of trusted certificates. Certificate ▸ Install into Firefox adds the WireLens certificate to every Firefox profile (it needs Mozilla's certutil: brew install nss). Restart Firefox afterwards. The Firefox recipe in Client Setup shows the proxy settings to enter.

Servers on localhost#

Traffic to localhost is captured. Some clients skip the proxy for localhost and private addresses because of the macOS proxy exceptions list. Point the client at the proxy explicitly and it always works:

curl -x http://127.0.0.1:9090 http://localhost:3000/

Proving it works#

Every recipe in the app comes with a one-line check under Then check it worked. Run it and look for the request in the traffic list. If the command succeeds and no row appears, the client went straight out: it never read the proxy variable. A certificate problem looks different: it shows up as a TLS error.