Settings

Cloak Proxy’s settings window has six pages: General, SSL Proxying, Bypass, Certificate, Network and Advanced. This page describes every option on each, with its default, and the few settings that live elsewhere.

Open Settings

• Choose Cloak Proxy › Settings… or press ⌘ ,.
• Press ⇧ ⌘ A and type the name of a page or option, such as Bypass List, External Proxy or Write TLS Keys for Wireshark. Every option below has its own search result that opens the right page. See Search and command palette.

The window remembers the last page you opened.

Which changes apply right away

Change	When it takes effect
Port and Allow other devices to connect on General	When you click Apply & Restart Proxy.
Everything on Network	When you click Apply & Restart Proxy. Revert discards your edits.
Bypass list	The next time you turn the macOS proxy on.
Everything else	Immediately.

Restarting the proxy briefly turns the macOS proxy off and back on, and closes open connections. Apps reconnect on their own.

General

12345

The General page, with the defaults.

1. The port Cloak Proxy listens on
2. Let phones and other computers connect
3. Applies port and device changes
4. Turn on macOS capture at launch
5. How much of each body to keep for inspection

×

Section	Option	Default	What it does
Listening	Port	9090	The port Cloak Proxy listens on, from 1 to 65535. Apps, devices and cloakctl connect to it.
Listening	Allow other devices to connect (phones, other computers)	Off	Listens on every network interface instead of only this Mac, so phones, tablets and other computers can use the proxy. When on, the page shows This Mac’s address (for example 192.168.1.20:9090) and a warning.
Listening	Apply & Restart Proxy		Applies the two options above. Dimmed until you change one.
macOS traffic	Capture macOS traffic when Cloak Proxy opens	On	Sets the macOS HTTP and HTTPS proxy to Cloak Proxy at launch and restores your previous settings when you quit. See macOS traffic.
HTTP/2	Offer HTTP/2 to apps on decrypted connections	On	Apps that support HTTP/2 (Chrome, curl, URLSession) talk HTTP/2 to Cloak Proxy on decrypted connections. Turn it off if an app misbehaves; apps then use HTTP/1.1.
Capture	Max captured body size	32 MB	Choose 1, 5, 10, 32, 64 or 128 MB. Larger bodies are still forwarded in full; only the first part is kept for inspection.

Other devices can use your proxy

With Allow other devices to connect on, anyone on your network can send traffic through Cloak Proxy. Limit it to your own devices with Allowed devices on the Network page, and turn it off when you’re done. See Other devices and access control.

SSL Proxying

HTTPS traffic to the hosts on this list is decrypted. Other HTTPS traffic passes through encrypted, as a tunnel. See SSL proxying.

1234

The SSL Proxying list starts empty.

1. On: turn a host off without deleting it
2. Type a host or pattern
3. Adds it to the list
4. Removes the selected row

×

Control	What it does
On	Turns a host pattern on or off without removing it.
Host	The pattern. Click to edit.
Text field	Type a pattern and press Return or click Add.
Add	Adds the pattern.
Remove	Removes the selected row.

Patterns can be an exact host (api.example.com), use * for any characters (*.example.com, api-*.test.dev) or ? for one character, add a port (example.com:8443), or be * alone to decrypt everything. Default: empty.

Apps whose HTTPS is decrypted for every host aren’t on this page. Turn them on from the sidebar: select an app and click Enable SSL Proxying for All Requests from the app, or right-click it.

Bypass

Hosts on this list skip Cloak Proxy entirely while the macOS proxy is on: macOS sends their traffic straight to the internet. Use it for hosts you never want to see or touch, such as internal services.

123

The Bypass list with its three default entries.

1. On: include the entry when the macOS proxy is set
2. Default entries
3. Add a host or pattern

×

Default entry	Covers
localhost	This Mac.
*.local	Bonjour names on your network.
169.254/16	Link-local addresses.

The controls are the same as on SSL Proxying. Changes apply the next time you turn the macOS proxy on, because they’re written into macOS’s proxy settings then. The list only affects apps that follow the macOS proxy; apps and devices configured to use Cloak Proxy directly still send everything to it.

Certificate

The root certificate lets Cloak Proxy decrypt HTTPS. This page shows it, installs and removes it, and holds client certificates for servers that require mutual TLS. See Certificate.

12345

The Certificate page on a Mac that trusts the certificate.

1. Whether macOS trusts the certificate
2. Install & Trust…, or Re-install once trusted
3. Make a new certificate (devices must trust it again)
4. Use your own root certificate and key
5. Add a client certificate for mutual TLS

×

Root certificate

Item	What it shows or does
Name	The certificate’s name: Cloak Proxy CA followed by your Mac’s name and the date it was made.
File	Where it’s stored: ~/Library/Application Support/CloakProxy/cloak-proxy-ca.pem.
Status	Trusted on this Mac or Not trusted.
Install & Trust…	Adds the certificate to your login keychain as a trusted root. macOS asks for your password. Reads Re-install once trusted.
Remove from Keychain	Removes the trust setting and deletes Cloak Proxy certificates from your login keychain. Available when trusted.
Show in Finder	Reveals the certificate file.
Copy PEM	Copies the certificate as PEM text, for installing on other devices or tools.
Regenerate Certificate…	Makes a new certificate and private key after you confirm. Devices and simulators that trust the old one need the new one installed.
Use My Own CA…	Uses an existing root certificate and private key instead. Select both PEM files at once in the file dialog.
Check Again	Rechecks whether macOS trusts the certificate.

Keep the private key private

The certificate and its private key are created on this Mac and never leave it. Anyone with the private key file (cloak-proxy-ca-key.pem, next to the certificate) could read traffic from any device that trusts your certificate. Don’t share it, commit it or copy it to other machines.

Client certificates (mutual TLS)

For servers that ask the client for a certificate. Cloak Proxy presents the .p12 certificate when it connects to a matching host. Default: none.

Field	What it’s for
On switch	Turns the entry on or off.
Host	The host it applies to, for example mtls.example.com or *.internal.example.com.
File (Choose…)	The .p12 or .pfx file with the certificate and its private key.
Password for the .p12 file	The file’s password.
Remove button	Deletes the entry.

Click Add Client Certificate to add one.

Network

Settings for how Cloak Proxy reaches the internet and who can reach it. Click Apply & Restart Proxy to apply changes, or Revert to discard them. If a listener can’t start, for example because its port is in use, the error appears next to these buttons. See Network settings.

12345

The Network page with nothing set up.

1. Chain to a corporate or other proxy
2. A SOCKS5 listener for clients that can't use an HTTP proxy
3. Forward a local port to a server and record it
4. Limit which devices may connect
5. Applies every change on this page

×

External proxy

Option	Default	What it does
Send outgoing traffic through another proxy	Off	Sends requests Cloak Proxy forwards through another proxy, such as a corporate proxy or another debugging tool.
Type	HTTP/HTTPS	HTTP/HTTPS or SOCKS5.
Host	Empty	The other proxy’s host.
Port	8080	The other proxy’s port.
Username (optional) and Password	Empty	Credentials for an HTTP/HTTPS proxy. Not shown for SOCKS5.

SOCKS

Option	Default	What it does
SOCKS5 proxy	Off	Starts a SOCKS5 listener on this Mac. Point SOCKS5 clients at 127.0.0.1 and the port. HTTPS is decrypted following your SSL Proxying rules.
Port	8889	The SOCKS5 port.

Reverse proxies

For apps that can’t use a proxy at all. Point them at http://localhost:PORT and Cloak Proxy forwards to the target and records the traffic. Click Add Reverse Proxy to add a row; the first one uses port 9000. Default: none.

Field	Default	What it does
On switch	On	Turns the row on or off.
localhost: port	9000 for the first row, then one more than the highest port in the list	The local port apps connect to.
Target	https://	The server to forward to, for example https://api.example.com.
Rewrite Host	On	Sends the target’s host name in the Host header instead of localhost.
Remove button		Deletes the row.

Allowed devices

When Allow other devices to connect is on, only addresses on this list may connect. Leave it empty to accept any device on your network. This Mac is always allowed. Click Add Address to add a row, prefilled with your network’s range, for example 192.168.1.*. Each row has an on switch, a pattern and a remove button. Default: empty. Refused connections are noted in the log file.

Advanced

1234

The Advanced page: TLS key logging, cloakctl and MCP setup.

1. Write TLS session keys for Wireshark
2. Copies the command that puts cloakctl on your PATH
3. Copies the Claude Code setup command
4. Copies JSON for Cursor and other MCP clients

×

Section	Option	Default	What it does
TLS key logging	Write TLS keys for Wireshark	Off	Writes TLS session keys in SSLKEYLOGFILE format, for both sides of each decrypted connection. Turning it on sets the file to ~/Desktop/cloak-proxy-sslkeys.log.
TLS key logging	Key log file	~/Desktop/cloak-proxy-sslkeys.log	Where the keys go. Shown while the option is on. In Wireshark, set it under Settings › Protocols › TLS › (Pre)-Master-Secret log filename.
Command line	cloakctl		The path of the command-line tool inside the app.
Command line	Link to /usr/local/bin		Copy copies a sudo ln -sf … command that puts cloakctl on your PATH. See cloakctl.
AI assistants (MCP)	Claude Code		Copy copies the claude mcp add cloak-proxy … command.
AI assistants (MCP)	Cursor / other (JSON)		Copy copies the mcpServers JSON for Cursor and other MCP clients. See MCP server.

Delete the key log when you're done

Anyone with the key log file can decrypt the matching packet captures. Turn the option off and delete the file when you no longer need it.

Settings outside the Settings window

Setting	Where to change it
Apps whose HTTPS is always decrypted	The sidebar, or the bar above the traffic list when an app is selected. See SSL proxying.
Captured domains for apps that ignore the proxy	The capture sheet from the Not Using the Proxy list. See Apps that ignore the proxy.
Debugging tool rules	The Tools window (⌥ ⌘ 0). See Tools overview.
Servers whose certificates aren’t checked (insecureUpstreamHosts)	Only through the control API’s update_settings, or the MCP tool of the same name. Use it for self-signed development servers.
API client preferences	The API client window.

Every proxy setting above (except the certificate files) can also be read with get_settings and changed with update_settings through the control API or MCP server.

Where settings are stored

Settings are saved in Cloak Proxy’s macOS preferences (domain com.subcloak.cloakproxy), on this Mac only. The certificate, its key and the API token are in ~/Library/Application Support/CloakProxy/. See Security and privacy.

Related

Network settingsPort, devices, HTTP/2, external proxy, SOCKS5 and reverse proxies in depth.

CertificateInstall, remove, regenerate or replace the root certificate.

SSL proxyingChoose which HTTPS traffic to decrypt.

TroubleshootingFix missing traffic, certificate errors and port problems.