The Local Bridge: Why Hoppscotch Agent Exists

Hoppscotch Agent exists because a browser-centered API workflow sometimes needs a native execution boundary. This chapter follows the Agent from local discovery and registration through encrypted request exchange, native relay execution, cancellation, and domain-specific settings. The goal is not to treat cryptography as decoration or to call the Agent “secure” in the abstract, but to identify what the visible boundary protects, what state it owns, and what assumptions remain outside it.

The Agent is best understood as a local bridge. The web application still prepares the request and presents the result, while a Tauri application running on the user's machine performs operations that a browser cannot perform directly. That division preserves the common workflow from earlier chapters, but it creates a relationship that must be established and maintained. A local service that can reach internal APIs, use client certificates, and route through configured proxies should not be treated like an ordinary public endpoint.

Discovery is not authorization

The first stage is local discovery. The browser-side Agent store checks a handshake endpoint on 127.0.0.1:9119 and records whether the expected Agent is running. The Agent server binds to that loopback address and exposes routes for handshake, registration, execution, cancellation, and related state operations. This tells the web application that a candidate local service exists; it does not by itself authorize the application to send sensitive request data through it.

That distinction explains why registration follows the handshake. Discovery answers “is something that identifies itself as the Agent listening here?” Registration answers “has this application instance established the credentials and shared secret needed for protected communication?” Treating the first answer as sufficient would leave the most important trust decision implicit. The Agent instead keeps availability and authorization as separate states that the UI can report and the request path can check.

The Agent persists registrations locally. The browser-side store keeps the auth key and a shared-secret representation, along with domain settings. The native side keeps registrations associated with shared secrets and uses them to validate later requests. Persistence is convenient because a user does not need to repeat the entire relationship for every request, but it is also part of the security boundary. A stale, removed, or mismatched registration can prevent execution; a local store is now holding material that controls access to the bridge.

Registration creates a relationship, not just a code

The user-facing registration flow uses a one-time code displayed through the Agent interface. The browser initiates a registration attempt, the Agent exposes the code, and the browser submits it along with a public key. The Agent creates an auth key and uses an X25519 key exchange to derive a shared secret known to both sides. The browser persists the resulting auth and secret state for future calls.

The important mechanism is the combination of two roles. The OTP is a human-mediated proof that the user is intentionally connecting the web application to the local Agent window. The public-key exchange creates a shared cryptographic value without sending that value as ordinary application data. The auth key then identifies the registration on subsequent routes. These pieces are not interchangeable: the code establishes user intent at registration time, the key exchange establishes shared material for protected payloads, and the bearer auth key lets the Agent look up the corresponding registration later.

The Agent's registration state can be cleared or removed. A reset on the browser side discards its auth and shared-secret state; the native side also supports deleting registrations. This lifecycle matters because local capability should not be permanent merely because it was once enabled. Registration is a state transition with a beginning, a usable period, and a possible termination—not a one-time UI ceremony that can be ignored after setup.

The source establishes the mechanism visible in this current implementation, but it does not establish every property a full security review would ask about.