Terminal and runtimes

Command-line tools usually ignore the macOS proxy and the macOS keychain. Instead they read proxy settings and certificate locations from environment variables. Cloak Proxy can open a Terminal window with those variables already set, or copy them as export commands for any shell, so Node.js, Python, Ruby, Go, curl, git, Deno and the AWS CLI send their traffic through it and trust its certificate.

Open a configured Terminal

1. Open Device & Runtime Setup (click Devices in the toolbar) and choose the This Mac tab.

2. Under Terminal: Node.js, Python, Ruby, Go, curl, git, click Open Configured Terminal.

   A new Terminal window opens and prints:

   Cloak Proxy: this shell's HTTP(S) traffic goes through 127.0.0.1:9090.
   Node, Python, Ruby, Go, curl and git trust the Cloak Proxy certificate here.

3. Run your program in that window.

Only programs started from that window are affected. Other Terminal windows and tabs aren’t. You don’t need the macOS proxy on, and you don’t need to let other devices connect.

12

The Terminal section of the This Mac tab.

1. Opens a Terminal window with the variables set
2. Copies the same variables as export commands

×

How it works

Cloak Proxy writes a short script to your temporary folder, named cloak-proxy-shell.command, readable only by you. The script exports the variables listed below, clears the screen, prints the two lines above, and then starts your usual login shell ($SHELL -l), which inherits the variables. macOS opens .command files in Terminal.

Copy export commands for any shell

Use Copy export Commands for a shell you already have open, an editor’s built-in terminal, iTerm, a Makefile or a CI script on your Mac. Cloak Proxy copies one export line per variable, with every value in single quotes, and shows Copied. Paste into any shell to configure it.

Copied export commands (example)

export http_proxy='http://127.0.0.1:9090'
export https_proxy='http://127.0.0.1:9090'
export HTTP_PROXY='http://127.0.0.1:9090'
export HTTPS_PROXY='http://127.0.0.1:9090'
export no_proxy='localhost,127.0.0.1'
export NO_PROXY='localhost,127.0.0.1'
export NODE_USE_ENV_PROXY='1'
export NODE_EXTRA_CA_CERTS='/Users/ada/Library/Application Support/CloakProxy/cloak-proxy-ca.pem'
export GLOBAL_AGENT_HTTP_PROXY='http://127.0.0.1:9090'
export SSL_CERT_FILE='/Users/ada/Library/Application Support/CloakProxy/ca-bundle.pem'
export REQUESTS_CA_BUNDLE='/Users/ada/Library/Application Support/CloakProxy/ca-bundle.pem'
export CURL_CA_BUNDLE='/Users/ada/Library/Application Support/CloakProxy/ca-bundle.pem'
export GIT_SSL_CAINFO='/Users/ada/Library/Application Support/CloakProxy/ca-bundle.pem'
export AWS_CA_BUNDLE='/Users/ada/Library/Application Support/CloakProxy/ca-bundle.pem'
export DENO_CERT='/Users/ada/Library/Application Support/CloakProxy/cloak-proxy-ca.pem'

The paths use your own home folder. The port is the one Cloak Proxy is listening on.

Environment variables it sets

Both buttons set the same variables.

Variable	Value	Why
http_proxy, HTTP_PROXY	http://127.0.0.1:9090	The proxy for plain HTTP requests. Tools differ in which spelling they read, so both are set.
https_proxy, HTTPS_PROXY	http://127.0.0.1:9090	The proxy for HTTPS requests. The value starts with http:// because tools talk to the proxy itself in plain HTTP and send HTTPS through a CONNECT tunnel.
no_proxy, NO_PROXY	localhost,127.0.0.1	Requests to local servers go directly, so your local dev server keeps working and isn’t sent back through the proxy.
NODE_USE_ENV_PROXY	1	Tells Node.js 24 and later to use the proxy variables for its built-in fetch and http modules.
NODE_EXTRA_CA_CERTS	Path to cloak-proxy-ca.pem	Node.js adds this certificate to its built-in list of trusted CAs.
GLOBAL_AGENT_HTTP_PROXY	http://127.0.0.1:9090	Read by the global-agent package, for older Node.js apps.
SSL_CERT_FILE	Path to ca-bundle.pem	The trust store for OpenSSL-based tools, including Ruby and Python’s ssl module.
REQUESTS_CA_BUNDLE	Path to ca-bundle.pem	The trust store for Python’s requests library.
CURL_CA_BUNDLE	Path to ca-bundle.pem	The trust store for curl.
GIT_SSL_CAINFO	Path to ca-bundle.pem	The trust store for git over HTTPS.
AWS_CA_BUNDLE	Path to ca-bundle.pem	The trust store for the AWS CLI and AWS SDKs.
DENO_CERT	Path to cloak-proxy-ca.pem	Deno adds this certificate to the CAs it trusts.

The CA bundle

Several tools replace their whole list of trusted CAs with the file you give them. Pointing them at the Cloak Proxy certificate alone would break every HTTPS connection Cloak Proxy doesn’t decrypt. So each time you click Open Configured Terminal or Copy export Commands, Cloak Proxy writes ca-bundle.pem next to its certificate in ~/Library/Application Support/CloakProxy/. It contains:

• the macOS system root certificates, and
• the Cloak Proxy root certificate.

Certificates your company added to the System keychain aren’t in the bundle. If a tool needs one, append it to the file yourself, and expect Cloak Proxy to overwrite the file the next time you click either button.

Note

Only hosts in SSL Proxying are decrypted. Requests to other hosts still go through Cloak Proxy and appear as encrypted tunnels.

Runtime snippets

Run these in a configured Terminal, or in a shell where you pasted the export commands.

Node.js

Node.js 24 and later use the proxy automatically here, for fetch and the http and https modules.

Terminal

node -e "fetch('https://api.example.com/v1/users').then(r => console.log(r.status))"

Older Node.js needs a proxy agent, for example undici’s EnvHttpProxyAgent or global-agent. Both read the variables Cloak Proxy sets.

Set up undici before your first request

import { setGlobalDispatcher, EnvHttpProxyAgent } from "undici";

setGlobalDispatcher(new EnvHttpProxyAgent());

Or preload global-agent

node -r global-agent/bootstrap app.js

Python

requests, urllib and the ssl module read the proxy variables and the CA bundle.

Terminal

python3 -c "import requests; print(requests.get('https://api.example.com/v1/users').status_code)"

Ruby

Net::HTTP reads http_proxy, and OpenSSL reads SSL_CERT_FILE.

Terminal

ruby -rnet/http -e "puts Net::HTTP.get_response(URI('https://api.example.com/v1/users')).code"

Go

Go’s default HTTP client reads HTTPS_PROXY, HTTP_PROXY and NO_PROXY. On macOS, Go checks certificates against the macOS keychain, so make sure the certificate is installed and trusted on this Mac (Settings › Certificate › Install & Trust…). See Certificate.

Terminal

go run ./cmd/server

curl

Terminal

curl https://api.example.com/v1/users

git

Terminal

git clone https://github.example.com/ada/project.git

Deno

Terminal

deno run --allow-net app.ts

AWS CLI

Terminal

aws s3 ls

Use the certificate path in scripts

The certificate lives at ~/Library/Application Support/CloakProxy/cloak-proxy-ca.pem. To print its path from a script, run cloakctl ca. Settings › Advanced shows where cloakctl is and a command to link it into /usr/local/bin. See cloakctl.

12

Link cloakctl into your PATH to use cloakctl ca in scripts.

1. Where cloakctl is inside the app
2. Copies the command that links it into /usr/local/bin

×

Terminal

export NODE_EXTRA_CA_CERTS="$(cloakctl ca)"

The private key stays put

The environment variables point at the certificate, never at its private key (cloak-proxy-ca-key.pem in the same folder). Don’t copy the key into projects, containers or CI. Anyone with it can decrypt traffic from every device that trusts your certificate.

Undo the setup

The variables live only in the shell that has them, so nothing on your Mac changes permanently.

• Configured Terminal: close the window, or type exit.

• Pasted export commands: close the shell, or unset the variables:

  Terminal

  unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY \
    NODE_USE_ENV_PROXY NODE_EXTRA_CA_CERTS GLOBAL_AGENT_HTTP_PROXY \
    SSL_CERT_FILE REQUESTS_CA_BUNDLE CURL_CA_BUNDLE GIT_SSL_CAINFO AWS_CA_BUNDLE DENO_CERT

If you added the export lines to a shell profile such as ~/.zshrc, remove them there too. Otherwise every new shell sends its traffic to 127.0.0.1:9090, and fails while Cloak Proxy isn’t running.

Related

Java, Firefox, Docker, Flutter and ElectronRuntimes that need their own settings.

Apps that ignore the proxyCapture apps that don't read proxy settings at all.

SSL ProxyingChoose which hosts are decrypted.

cloakctlThe command-line tool, including cloakctl ca.