Routing Hoppscotch Requests Through the Local Agent to Bypass Browser CORS Limits

The problem: browser sandbox blocks local API calls

When you use the Hoppscotch web app to call an API running on localhost or on a private network, the browser often refuses to deliver the response. This happens because browsers enforce the same-origin policy, a security rule that stops a page from reading data returned by a different origin unless the server explicitly allows it through CORS (Cross-Origin Resource Sharing) headers. The Hoppscotch web app runs inside the browser, so it inherits that restriction. A local development server usually does not send the permissive CORS headers that a public API might, which means the request either fails in the console or returns an opaque error.

The practical workaround is to move the HTTP call outside the browser. The Hoppscotch Agent is a local proxy process that runs on your workstation. When the web app is set to Agent mode, it hands the request to that process, the Agent forwards it to the target server, and relays the response back. Because the actual network call is made by the Agent rather than the page, the browser's same-origin policy no longer blocks it.

Desired outcome

You want to send requests from the Hoppscotch web app to local or internal endpoints and receive real responses—status codes, headers, and bodies—without modifying the target server's CORS configuration and without seeing browser-origin errors in the console.

Prerequisites

• The Hoppscotch web app open in a supported browser.
• A local or internal API endpoint reachable from your machine. For example, a service listening on http://localhost:8080/status.
• The Hoppscotch Agent available on the same workstation, either as a browser extension or as a local CLI process.
• Confirmation that your Hoppscotch version uses the Agent mode described here. Installation commands, supported browsers, and default ports vary by release, so verify the current documentation for your version before relying on a specific command or port.

Procedure: switch Hoppscotch to Agent mode

Start the Agent process

If you are using the CLI Agent, open a terminal on your workstation and start it. The exact invocation depends on your installation method; use the start command documented for your release, for example the package's binary or an npx-style command. Run it as your normal user. Administrative rights are typically not required unless the Agent is configured to bind to a privileged port below 1024, which is uncommon for local development.

Risk: The Agent opens a local listening port. Some corporate endpoint-security tools or network policies may flag or block unrecognized local listeners. If the process starts but the web app cannot reach it, check local firewall rules and security software logs.

Change the proxy setting in Hoppscotch

In the Hoppscotch web app, locate the proxy or interceptor settings. The default mode usually routes requests through Hoppscotch's hosted proxy. Switch the setting to Agent so the browser delegates outbound HTTP calls to the local process instead. The exact menu label can differ between versions; look for a proxy destination selector that offers a local or Agent option alongside the default hosted proxy.

Send a test request

Create a request in Hoppscotch pointing at your local endpoint. For example:

GET http://localhost:8080/status HTTP/1.1

Send it. In Agent mode, the browser passes the request details to the local Agent, which opens its own connection to http://localhost:8080/status and returns the response to the web app.

Expected checks

Confirm the change worked with three practical checks:

1. Browser console: Open the developer console. A successful Agent-routed request should not produce a CORS error. If you still see messages like "blocked by CORS policy" or "No 'Access-Control-Allow-Origin' header," the request is still being made by the page, not the Agent.
2. Agent output: Check the terminal or log window where the Agent is running. It should show that it received a request and forwarded it to the target address. If the Agent log is silent, the web app is probably not configured to use Agent mode.
3. Negative control: Switch the proxy setting back to the default hosted mode and resend the same request. If the local endpoint does not send permissive CORS headers, the browser should now block the response. Seeing the failure in default mode and success in Agent mode proves the Agent is what enabled the call.

Recovery options

If requests fail after setup, work through these recovery paths:

• Agent not running: The Agent process must stay alive for the duration of your testing. If the terminal is closed or the process exits, subsequent requests will fail. Restart the Agent and resend.
• Wrong proxy mode: If the browser still reports CORS errors, re-check the Hoppscotch proxy setting. Agent mode is easy to overlook after a page refresh or version update.
• Port or network block: If the Agent starts but the web app cannot connect, a corporate security tool may be blocking the local proxy port. Try the browser-extension variant of the Agent if available, or consult your endpoint-security documentation for allowed local ports.
• Target unreachable: Verify the endpoint independently. From the same workstation, run a direct request such as curl http://localhost:8080/status in a terminal. If that fails, the problem is the target service, not Hoppscotch or the Agent.

Limitations and security notes

The Agent is a trusted local process. It receives the full contents of every request you route through it, including headers, authentication tokens, and request bodies. Only run the Agent on machines you control, and avoid sending production credentials through it during routine local testing. Stop the Agent when you are finished if your workflow does not require it to persist.

Agent behavior is version-dependent. Browser support, default ports, and installation commands can change between Hoppscotch releases. Treat the steps above as a pattern rather than a fixed version-specific runbook, and verify the exact settings against the documentation for the Hoppscotch version you are using.