Java, Firefox, Docker, Flutter and Electron

Some runtimes keep their own proxy settings or their own list of trusted certificates, so the macOS proxy and keychain don’t reach them. The Other tab of Device & Runtime Setup has a ready-made command or setting for each of them, filled in with your port and the path of your certificate. Each has a Copy button.

12345

The Other tab. Commands use your port and your certificate's path.

1. Copy copies the command exactly as shown
2. Firefox setting
3. Docker command (finish it with your image and command)
4. Flutter / Dart proxy setting
5. Launch flag for Electron and Chromium apps

×

In the commands, the certificate path is written as $HOME/Library/Application Support/CloakProxy/cloak-proxy-ca.pem so you can paste it into a shell. The port is the one Cloak Proxy listens on (9090 by default).

Java (JVM, Gradle, Android Studio)

Java uses its own trust store, cacerts, and its own proxy settings.

1. Import the Cloak Proxy certificate into the JDK’s trust store. Copy the command from the Java (JVM, Gradle, Android Studio) section and run it:

   Terminal

   sudo keytool -importcert -noprompt -alias cloak-proxy -cacerts -storepass changeit -file "$HOME/Library/Application Support/CloakProxy/cloak-proxy-ca.pem"

   changeit is the JDK’s default trust store password. -cacerts needs Java 9 or later.

2. Run your program with the proxy settings:

   Terminal

   java -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=9090 -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=9090 -jar app.jar

keytool changes the JDK it belongs to. If you use more than one JDK (Android Studio bundles its own), run the keytool of each JDK that should trust the certificate. A JDK update can replace cacerts, so import again after updating.

To pass the proxy settings without editing a command line, set them in the environment or, for Gradle, in gradle.properties:

Any Java program

Terminal

export JAVA_TOOL_OPTIONS="-Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=9090 -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=9090"

Gradle

gradle.properties

systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=9090
systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPort=9090

Undo: remove the certificate and the proxy settings.

Terminal

sudo keytool -delete -alias cloak-proxy -cacerts -storepass changeit

Firefox

Firefox uses the macOS proxy by default, so it’s captured when the macOS proxy is on. It doesn’t trust the macOS keychain by default, though, so HTTPS fails until you change one setting.

1. Make sure the certificate is trusted on this Mac (Settings › Certificate › Install & Trust…). See Certificate.

2. In Firefox, open about:config and accept the warning.

3. Search for security.enterprise_roots.enabled and set it to true.

Firefox then trusts certificates in the macOS keychain, including Cloak Proxy’s. The Copy button copies the line as shown in the app (about:config → security.enterprise_roots.enabled = true), as a reminder rather than a command.

Undo: set security.enterprise_roots.enabled back to false.

Docker containers

Containers reach your Mac through host.docker.internal. Point them at Cloak Proxy there, and mount the certificate so the container can trust it.

1. In Settings › General, turn on Allow other devices to connect (phones, other computers) and click Apply & Restart Proxy. By default Cloak Proxy listens only on 127.0.0.1 for this Mac’s own apps; the Docker containers section asks you to turn this on so containers can reach it.

2. Copy the command from the Docker containers section. It ends with …: replace that with your own options, image and command.

   Terminal

   docker run -e HTTP_PROXY=http://host.docker.internal:9090 -e HTTPS_PROXY=http://host.docker.internal:9090 -v "$HOME/Library/Application Support/CloakProxy/cloak-proxy-ca.pem":/usr/local/share/ca-certificates/cloak-proxy.crt …

3. Inside the container, run update-ca-certificates before your program, so the system trust store includes the mounted certificate. For example, with an image based on Debian or Ubuntu that has the ca-certificates package:

   Terminal

   docker run --rm \
     -e HTTP_PROXY=http://host.docker.internal:9090 \
     -e HTTPS_PROXY=http://host.docker.internal:9090 \
     -v "$HOME/Library/Application Support/CloakProxy/cloak-proxy-ca.pem":/usr/local/share/ca-certificates/cloak-proxy.crt \
     your-image sh -c "update-ca-certificates && your-command"

Caution

Mount only cloak-proxy-ca.pem, never the folder it’s in. The same folder holds the certificate’s private key, cloak-proxy-ca-key.pem, and anyone with that key can decrypt traffic from every device that trusts your certificate.

If you use Allowed devices in Settings › Network, containers’ connections must match an entry. When Cloak Proxy refuses a connection, it writes the address to its log at ~/Library/Logs/CloakProxy/cloak-proxy.log: Refused a connection from <address>: not in the allowed client list. See Other devices and access control.

Undo: remove the -e and -v options from your docker run command, and turn off Allow other devices to connect when you’re done.

Flutter and Dart

Dart’s HttpClient ignores the system proxy, so Flutter apps need the proxy set in code. Copy the line from the Flutter / Dart section:

Dart

HttpClient()..findProxy = (uri) => 'PROXY 127.0.0.1:9090';

Use it where your app creates its HttpClient, or pass that client to the HTTP library you use. Only do this in debug builds.

127.0.0.1 means “this device”. Pick the address that reaches your Mac from where the app runs:

Where the app runs	Proxy address
macOS app or iOS Simulator	127.0.0.1:9090
Android emulator or USB device after Connect Proxy on the Android tab	127.0.0.1:9090 (forwarded by adb reverse)
iPhone, iPad or Android device over Wi-Fi	Your Mac’s address, for example 192.168.1.20:9090, with Allow other devices to connect on

The app must also trust the Cloak Proxy certificate. Install it on the device (iPhone and iPad, iOS Simulator, Android). In debug builds you may also need badCertificateCallback:

Dart (debug builds only)

final client = HttpClient()
  ..findProxy = (uri) => 'PROXY 127.0.0.1:9090'
  ..badCertificateCallback = (cert, host, port) => true;

Never ship badCertificateCallback returning true

A callback that returns true accepts any certificate, so anyone on the network could read and change the app’s traffic. Keep it behind a debug-only check, or install the CA on the device instead.

Undo: remove the findProxy and badCertificateCallback lines, or keep them behind a debug flag that’s off.

Electron and Chromium apps

Electron apps and other Chromium-based apps often ignore the macOS proxy. They do trust the macOS keychain, so only the proxy flag is needed. Copy the command from the Electron / Chromium apps section and put the app’s name in place of App Name:

Terminal

open -a "App Name" --args --proxy-server=127.0.0.1:9090

1. Make sure the certificate is trusted on this Mac (Settings › Certificate › Install & Trust…).

2. Quit the app completely. If it’s still running, open only brings it to the front and the flag is ignored.

3. Run the command.

Undo: quit the app and open it normally. The flag lasts only for that launch.

If an app ignores the flag too, see Apps that ignore the proxy, or point it at a reverse proxy in Settings › Network (Network settings).

Related

Terminal and runtimesNode.js, Python, Ruby, Go, curl, git, Deno and AWS CLI.

Apps that ignore the proxyCapture apps that skip proxy settings entirely.

CertificateInstall and trust the root certificate on this Mac.

Other devices and access controlAllow containers and devices to connect safely.