Map remote
Map remote sends the requests that match a URL to another server instead of the one the app asked for. The app gets that server’s answer.
Add one
Section titled “Add one”- For one URL: right-click a request › Map remote…, then fill in To. The rule matches that URL with any query string.
- For a host or folder: right-click it in Structure › Map remote…
- From scratch: Breakpoints panel › + › Map remote…, then fill in the URL and To.
The rule’s URL and Method work as they do for breakpoints. Its switch turns it off. The rule does nothing until To names a server; a To that zhttp can’t use is outlined in red.
To is a URL. Its scheme, host and port replace the request’s, and Host (or :authority) is set to match.
| To | https://api.example.com/v1/users?page=2 goes to |
|---|---|
https://staging.example.com |
https://staging.example.com/v1/users?page=2 |
http://localhost:4000 |
http://localhost:4000/v1/users?page=2 |
http://localhost:4000/users |
http://localhost:4000/users?page=2 |
http://localhost:4000/users?debug=1 |
http://localhost:4000/users?debug=1 |
- No path: the request keeps its path and query.
- A path: it replaces the request’s path. The query stays, unless To has one.
- A path ending in
*: the*stands for what the*at the end of the rule’s URL matched. URLhttps://api.example.com/v1/*with Tohttps://api.example.com/v2/*sends/v1/users?page=2to/v2/users?page=2.
Plain http:// requests can be mapped to https:// servers and the other way round.
How it goes
Section titled “How it goes”- The request goes to the other server over HTTP/1.1, on a connection zhttp opens with the app’s own TLS hello, naming the other server.
- WebSockets follow the map, whether the app opens them with an HTTP/1.1 upgrade or over HTTP/2.
- An HTTP/2 request that is mapped isn’t also held by a breakpoint or mapped to a file.
- gRPC can’t be mapped: it needs HTTP/2 to the server.
- With an upstream proxy set, the connection to the other server goes through it too.
- If the other server can’t be reached, the app gets a
502that says why.
In the list
Section titled “In the list”A mapped request is listed as it went: with the other server’s URL, and a blue mark beside the status stripe. Hover its path to see the URL the app asked for. AI agents see that URL as mapped_from.
Replay and the composer start from the URL the app asked for, so the request is mapped again while the rule is on.
Map remote rules are saved with the session, like breakpoints.