Network settings

These settings control how Cloak Proxy listens for traffic and how it sends traffic on. Most people only change them to debug a phone or another computer, to work behind a corporate proxy, or to capture a client that can’t use an HTTP proxy. They live on two pages: Settings › General and Settings › Network.

Settings at a glance

Setting	Page	Default	Applies
Port	General	9090	After Apply & Restart Proxy
Allow other devices to connect	General	Off	After Apply & Restart Proxy
Offer HTTP/2 to apps on decrypted connections	General	On	At once, for new connections
Max captured body size	General	32 MB	At once, for new requests
External proxy	Network	Off	After Apply & Restart Proxy
SOCKS5 proxy	Network	Off, port 8889	After Apply & Restart Proxy
Reverse proxies	Network	None	After Apply & Restart Proxy
Allowed devices	Network	Empty (any device, when other devices may connect)	After Apply & Restart Proxy
Insecure upstream hosts	MCP or control API only	None	At once

Capture macOS traffic when Cloak Proxy opens, also on the General page, is covered in Capture macOS traffic.

Change the port

Cloak Proxy listens on port 9090 by default. Change it if another program already uses that port, or if you run more than one proxy.

12345

Settings › General.

1. The port Cloak Proxy listens on
2. Let phones and other computers connect
3. Apply port and device changes
4. Offer HTTP/2 to apps
5. Largest body kept for inspection

×

1. Open Cloak Proxy › Settings… (⌘ ,) and click General.

2. Enter a port between 1 and 65535 in Port.

3. Click Apply & Restart Proxy.

Cloak Proxy restarts the proxy on the new port. If macOS capture is on, it turns the macOS proxy off and back on so it points at the new port. Update the port on any device, Terminal or tool you configured by hand.

If the port is taken, the toolbar pill turns red and reads Not listening. Hover it to see Couldn’t listen on port followed by the port and the reason, then choose another port.

Allow other devices to connect

By default Cloak Proxy listens only on 127.0.0.1, so only this Mac can use it. To debug a phone, a tablet, another computer, or a Docker container, let other devices connect.

1. Open Settings › General and turn on Allow other devices to connect (phones, other computers).

   The settings show This Mac’s address, for example 192.168.1.20:9090. Use it as the proxy on the other device.

2. Click Apply & Restart Proxy.

   The toolbar pill now shows 0.0.0.0:9090: Cloak Proxy listens on every network interface.

The iPhone & iPad page of Device & Runtime Setup also has an Allow Other Devices to Connect button that does the same in one click. See Other devices and access control.

The SOCKS5 proxy and reverse proxies listen on the same interfaces as the main proxy, so they also accept other devices while this is on.

Turn it off when you're done

While other devices may connect, anyone on your network can send traffic through Cloak Proxy, and you’ll see it. The settings warn: Anyone on your network can use this proxy while it’s on. Turn it off when you’re done with device debugging. On a shared network, also list your devices under Allowed devices.

Accept only some devices

The allowed devices list limits which addresses may connect while other devices are allowed. When it’s empty, any device on your network is accepted. This Mac is always allowed.

12345

Settings › Network. Changes on this page take effect when you click Apply & Restart Proxy.

1. Send outgoing traffic through another proxy
2. Accept SOCKS5 clients
3. Forward a local port to a server
4. Accept only these device addresses
5. Apply the changes and restart the proxy

×

1. Open Settings › Network.

2. Under Allowed devices, click Add Address.

   A new entry appears, filled in with your Mac’s subnet, for example 192.168.1.*.

3. Edit it to match one device (192.168.1.42) or a range (192.168.1.*). Add more entries if you need them.

4. Click Apply & Restart Proxy.

Control	What it does
Switch	Turns the entry on or off. Entries that are off don’t count.
Address field	An IP address or a pattern. * matches any characters and ? one character, like host patterns.
Minus button	Deletes the entry.
Add Address	Adds an entry for your Mac’s subnet.

Cloak Proxy closes connections from addresses that don’t match and records Refused a connection from the address : not in the allowed client list in ~/Library/Logs/CloakProxy/cloak-proxy.log.

Caution

The allowed devices list is checked on the main proxy port, the SOCKS5 port and reverse-proxy ports. Connections from other addresses are refused and logged.

Offer HTTP/2 to apps

Offer HTTP/2 to apps on decrypted connections is on by default. On decrypted HTTPS connections, Cloak Proxy then offers HTTP/2 as well as HTTP/1.1, and apps that support it (Chrome, curl, URLSession) use HTTP/2 with Cloak Proxy. Each HTTP/2 stream appears as its own request. Apps that don’t support HTTP/2 keep using HTTP/1.1.

Turn it off if an app misbehaves through Cloak Proxy. New decrypted connections then use HTTP/1.1 only. The setting doesn’t affect how Cloak Proxy talks to servers.

Limit the captured body size

Max captured body size sets the largest request or response body Cloak Proxy keeps for inspection. Choose 1 MB, 5 MB, 10 MB, 32 MB (the default), 64 MB or 128 MB.

Larger bodies are still forwarded in full: the app and the server always get the complete body. Cloak Proxy keeps only the first part for the inspector, exports and Insights. A smaller limit saves memory when you capture large downloads. The change applies to new requests.

Send traffic through another proxy

An external proxy (an upstream proxy) is a proxy that Cloak Proxy sends its own outgoing requests through: a corporate proxy that your network requires, or another debugging tool you want to chain with.

1. Open Settings › Network and turn on Send outgoing traffic through another proxy.

2. Choose the Type: HTTP/HTTPS or SOCKS5.

3. Enter the proxy’s Host and Port.

4. For an HTTP/HTTPS proxy that needs a login, enter Username (optional) and Password.

5. Click Apply & Restart Proxy.

Field	Details
Type	HTTP/HTTPS for a regular web proxy, SOCKS5 for a SOCKS proxy.
Host	The proxy’s host name or IP address. The external proxy is only used when this is filled in.
Port	The proxy’s port. Defaults to 8080.
Username (optional) and Password	Sent to an HTTP/HTTPS proxy with Basic authentication. Not available for SOCKS5.

The external proxy applies to requests Cloak Proxy reads and sends on: plain HTTP, decrypted HTTPS, and requests you repeat or compose. Encrypted tunnels that Cloak Proxy only relays, and WebSocket connections, connect to the server directly. If your network allows internet access only through the corporate proxy, turn on SSL Proxying for the hosts you need.

Note

The proxy password is saved with Cloak Proxy’s settings in its preferences file. The MCP tool get_settings shows it as ••••.

Accept SOCKS5 clients

Some clients can use a SOCKS5 proxy but not an HTTP proxy. Cloak Proxy can listen for SOCKS5 too.

1. Open Settings › Network and turn on SOCKS5 proxy.

2. Change the Port if you like. The default is 8889.

3. Click Apply & Restart Proxy.

4. Point the client at 127.0.0.1:8889.

Cloak Proxy handles SOCKS5 connections like HTTPS tunnels: TLS traffic is decrypted following your SSL Proxying rules, and plain HTTP is read and recorded. The SOCKS5 listener supports connections without authentication (CONNECT only).

Forward a local port with reverse proxies

A reverse proxy is for clients that can’t use a proxy at all. You point the client at a local port, and Cloak Proxy forwards every request on that port to one fixed server and records the traffic.

1. Open Settings › Network and click Add Reverse Proxy under Reverse proxies.

   A row appears with the port after the highest one in the list (9000 for the first one) and the target https://.

2. Change the local port if you like, and enter the target, such as https://api.example.com.

3. Leave Rewrite Host checked unless the server expects localhost.

4. Click Apply & Restart Proxy.

5. Point the client at http://localhost:9000 instead of https://api.example.com.

Control	What it does
Switch	Turns the reverse proxy on or off.
localhost: and port	The local port the client connects to, over plain HTTP.
Target	Where requests go: an http:// or https:// URL with a host and optional port, such as https://api.example.com or http://staging.example.com:8080.
Rewrite Host	Sends the target’s host name (and port, if it isn’t the default) in the Host header instead of localhost. On by default.
Minus button	Deletes the reverse proxy.

If a reverse proxy can’t start, the error appears at the bottom of Settings › Network in orange, and in an alert after the restart. For example, Reverse proxy on port 9000: followed by isn’t an http(s) URL when the target is invalid, or the reason the port can’t be used.

Skip certificate checks for some servers

When Cloak Proxy connects to a server, it checks the server’s certificate like any HTTPS client. Development and staging servers with self-signed certificates fail that check. Insecure upstream hosts are hosts whose certificates Cloak Proxy doesn’t check.

There’s no control for this in Settings. Set the list with the MCP tool update_settings and the key insecureUpstreamHosts, or with the control API. get_settings shows the current list. Requests to these hosts are labeled Insecure TLS in the traffic list’s Path column. See MCP server and Control API.

Danger

Without certificate checks, Cloak Proxy can’t tell the real server from an impostor. Add only development servers you control, never production hosts, and remove them when you’re done.

Apply, revert and restart

• On Settings › General, Apply & Restart Proxy applies the port and Allow other devices to connect. It’s dimmed until you change one of them. The other General settings apply at once.
• On Settings › Network, every change waits for Apply & Restart Proxy. Revert throws away changes you haven’t applied. Both are dimmed until you change something.

Restarting the proxy closes open connections, so apps reconnect.

The same settings are available to scripts and AI assistants through the MCP tools get_settings and update_settings. For a headless proxy, cloakctl run takes --port and --all-interfaces. See cloakctl.

Related

Other devices and access controlConnect phones and other computers safely.

Devices overviewSet up iPhone, Android, simulators and runtimes.

Settings referenceEvery settings page and option.

Capture macOS trafficThe system proxy, auto-on and bypass list.