Map Remote

Map Remote sends matching requests to a different server. You choose which parts of the URL to change (scheme, host, port, path or query) and leave the rest as the app sent it. Use it to point a production build at staging, try a local dev server with a real app, or compare two versions of an API without rebuilding anything.

Send requests to another server

1. Right-click a request from the server you want to replace and choose Tools › Map Remote….

   Cloak Proxy creates a rule that matches the request’s URL (without its query string) for any method, with subpaths on, and fills Host with the current host. It turns Map Remote on and opens the rule.

2. Change the matcher if you want more of the API mapped. For a whole host, use https://api.example.com/.

3. Under Send to, fill in only the parts that should change. For staging, change Host to staging.example.com.

4. Check the Preview line, then make the request again. The traffic list shows the new URL with a Map Remote badge.

12345

Empty fields keep the original value. The preview shows the result.

1. Scheme: http or https.
2. Host to send requests to.
3. Path: replaces the whole path.
4. Keep the Host header the app sent.
5. Preview: the original URL struck through, and the rewritten one.

×

Send to fields

Every field is optional. An empty field keeps that part of the original URL, as its placeholder says (unchanged).

Field	Example	What it does
Scheme	http	Switches between http and https. Entered in any case; sent in lowercase.
Host	staging.example.com	The server to connect to.
Port	3000	A port number. When it’s the default for the scheme (443 for HTTPS, 80 for HTTP) it’s left out of the URL.
Path	/v2/users	Replaces the whole path. A missing leading / is added.
Query	debug=1	Replaces the whole query string. A leading ? is optional.
Keep the original Host header	Off	When off, the Host header is set to the new host (and port, if it isn’t the default). When on, the app’s original Host header is sent to the new server.

Examples

For the request https://api.example.com/v1/users?page=2:

You set	The request goes to
Host staging.example.com	https://staging.example.com/v1/users?page=2
Scheme http, Host localhost, Port 3000	http://localhost:3000/v1/users?page=2
Path /v2/users	https://api.example.com/v2/users?page=2
Query debug=1	https://api.example.com/v1/users?debug=1

Path and Query replace, they don't merge

Path replaces the entire path, not a prefix. A rule matching api.example.com/v1/* with Path /v2/users sends every /v1/… request to /v2/users. To move a whole API version, use one rule per endpoint, or change the URL in a script where you can rewrite part of the path. In the same way, Query replaces every query parameter.

Preview

Below the fields, Preview shows an example URL built from your matcher (each * replaced by example, and https:// added when the pattern has no scheme), struck through, and under it the URL Map Remote would send. It updates as you type.

When to keep the Host header

Most servers need a Host header that matches their own name, so leave Keep the original Host header off. Turn it on when the new server routes by the original name, for example:

• A load balancer or reverse proxy at an IP address that serves several sites.
• A local server that expects the production host name.

To keep the URL and Host header and only change which machine you connect to, DNS Spoofing is often simpler.

How Map Remote works with other tools

• Map Remote matches the request after request scripts and the request breakpoint, and runs after Map Local and Mock Sets. If either answers the request, Map Remote doesn’t run.
• Only the first matching Map Remote rule is used.
• DNS Spoofing and No Caching apply to the rewritten request.
• Response scripts and the response breakpoint still match the original URL. Alerts match the rewritten URL, which is also what the traffic list shows.

Certificates

Cloak Proxy checks the new server’s HTTPS certificate against its host name, as for any request. If a local or staging server uses a self-signed certificate, the request fails with a certificate error. Add that host to the insecure upstream hosts in Network settings, or switch the rule’s Scheme to http if the server supports it.

Caution

A Map Remote rule keeps sending traffic to the other server until you turn it off, even after a restart. Before you test against production again, check the status bar for a Map Remote chip.

Related

DNS SpoofingConnect a host to another IP without changing the URL.

Map LocalAnswer requests from your Mac instead of a server.

Rules and matchingPatterns, subpaths and the order tools run in.

Network settingsInsecure upstream hosts, external proxies and more.