Skip to main content
Send the proxy browser’s traffic out through your own IP address, so merchants see your connection instead of a datacenter’s.

​
Overview

The proxy runs the browser in the cloud. Without a tunnel, merchants see the proxy’s datacenter address, which many sites block or challenge. A checkout that works from your laptop can hit a bot wall from the proxy. With a tunnel, the SDK opens a reverse SOCKS5 tunnel over its existing proxy connection. The browser’s traffic is routed back through your machine and exits from your address.
  • On by default, as a preference. The SDK asks for a tunnel and falls back to the proxy’s address, or the deployment’s residential egress where one is configured, with a warning, if one cannot be set up.
  • You relay only encrypted bytes. Substitution happens inside the proxy’s browser, above the transport you relay, so you never see card data, passwords or any other real value.
  • Your network stays private. The tunnel refuses to reach private and LAN addresses, so a merchant page cannot use it to probe your network.

​
Choose a mode

The launch option overrides the environment variable. The MCP server reads the same variable. “Exits from the proxy” means the deployment’s own egress: the proxy’s address, or its residential egress where one is configured.

​
When to require the tunnel

Require it when exiting from your address is a promise you have made, for example to a merchant that blocks datacenter traffic. A required tunnel never falls back silently: an agent told it is exiting from your IP, quietly exiting from a datacenter IP instead, would be a promise broken without a signal. A required launch against a proxy that does not establish the tunnel throws before any browser starts, and the message says to set SELF_AGENT_PAY_TUNNEL=0 if direct egress is acceptable.

​
Plaintext is never relayed through you

In a tunnelled session the proxy splits traffic by scheme: Without a tunnel, whether because it is off or because a preferred tunnel fell back, there is no split. Everything leaves from the session’s single egress: the proxy’s own address, or the deployment’s residential egress when one is configured. Residential egress carries HTTPS only, so a plain http request never leaves at all (see HTTPS only).
Do not read a tunnel-less checkout as preserving your address. Without a tunnel, the merchant sees the proxy’s address, or the deployment’s residential exit, never yours.
Token fills on plaintext pages are refused regardless, with insecure_page, except on a loopback address such as http://localhost used for a local demo (see URL locking). On plaintext, anyone on the network path between the proxy and the merchant could read a card number, password or authenticator code typed into the page.

​
Residential egress

On a deployment with a residential provider, a session without a tunnel through your machine leaves through that provider instead of the proxy’s own address. That covers tunnel: false, a preferred tunnel that fell back, and every session on the hosted MCP server. Sites see a home address in one country, chosen as described in Residential egress country.
  • Used, or required. Where the deployment has a provider, a session without a tunnel uses it with nothing to set. To refuse to start without it, launch with residentialEgress: true or set SELF_AGENT_PAY_RESIDENTIAL_EGRESS=1. launch() then fails with egress_unavailable and a retryAfterSeconds when the deployment has no provider, or the provider does not answer for your country. A working tunnel through your machine satisfies the requirement too.
  • Never a silent fallback. If the proxy cannot set up the residential route for a session, launch() fails with “residential egress setup failed” rather than sending the session out from the proxy’s address.
  • Lost mid-session. If the provider stops carrying the session, every later call except outcome() and the close calls fails with egress_lost. Nothing leaves from any other address. Close the session and launch a new one.

​
HTTPS only

A residential egress session never sends anything over plain http. When the HTTPS attempt fails (no TLS on the host, a certificate the browser will not accept, no answer) or the server redirects to http://, a goto() fails with insecure_site, and the tab stays on the page it was on. Nothing was sent over plain http, and retrying the same address fails the same way, so choose another site. A click() or press() whose navigation is stopped this way gets the browser’s own navigation error instead. See insecure_site.

​
Which exit a session used

When a residential egress session ends, Agent Vault records one egress_used event for the account holder. It shows on Activity as Residential exit, with the title “Residential exit used”, and says:
  • The country the exit was in.
  • How much the session carried: bytes sent and bytes received.
  • How many attested checkouts went out through the same exit, when there were any.
  • Whether the provider stopped carrying the session before it ended.
It never names an IP address. The provider picks the exit inside its own network, so Agent Vault never learns it. There is at most one event per proxy session, and none for a session that never reached a site. It is best effort, like the rest of Activity. The event is always recorded. Email and desktop alerts for it are off by default: the account holder turns them on with Which residential exit my agent’s session used in Settings.

​
Residential egress country

Without a tunnel, a deployment with a residential provider sends each session out from a home address in one country. Card issuers compare where a purchase comes from with the card’s billing address, so Agent Vault picks that country from your account when the session starts, in this order:
  1. The billing country of the cards your API key may use, if they all agree on one. If the key may use more than 20 cards, this step is skipped.
  2. Otherwise, the country of your saved addresses, if they all agree on one. If you have more than 20 saved addresses, this step is skipped.
  3. Otherwise, the fallback country the deployment is configured with.
A disagreement never picks a winner. A key with a US card and a Canadian card moves on to your addresses, and if those disagree too, the session leaves from the fallback country, which may not be yours. To keep sessions in your own country, give a key only cards billed in that country.

​
When traffic did not use the tunnel

If any of a session’s traffic did not go out through your tunnel, Agent Vault tries to notify the account owner with an untunneled_egress event (best effort). It names the reason: the tunnel was unavailable (including a preferred tunnel that fell back), or the traffic was plaintext and took the direct route by design. Plaintext exposure is reported only when it was observed. When a preferred tunnel was unavailable, the event says the traffic was readable on the way only if the proxy saw plain http traffic in the session. A session the proxy saw use only https stayed encrypted, and the event says so. Traffic the proxy cannot watch, such as an attested checkout’s own browser, gets neither claim. The direct-route case is always plain http, so it is always reported as readable. The event is reported once, when the session ends, so there is at most one per proxy session. For plain http traffic, the event names the first five sites the session reached that way and counts the distinct sites, up to 100. Past 100 it stops counting and does not say that more were left out, so a count of 100 is a lower bound. The alert text names the first three sites and counts the rest. When the tunnel was unavailable, the event names no plain http sites, because the whole session went out another way. Merchants an attested checkout reached are named and counted separately, with the same limits, and there the alert says “at least” once it stops counting. See Ceilings.

​
Tunnelling and attested checkout

The attested checkout runs its own browser inside a confidential-compute enclave.
  • Where the deployment relays the enclave’s traffic, an attested checkout in a tunnelled session goes out through your tunnel too.
  • Where it cannot, a session that required the tunnel is refused up front with attested_checkout_unavailable, and nothing is recorded. Open a session without tunnel: true, or fill the card token on your own page.
  • In a session that only preferred the tunnel, an unrelayed attested checkout exits from the enclave’s address, and the owner is told through untunneled_egress.
  • In a residential egress session, a relayed attested checkout goes out through the residential exit and is counted in the egress_used event. An unrelayed one exits from the enclave’s address, and the owner is told through untunneled_egress, whatever the session asked for.
If a required tunnel drops while the owner is deciding a purchase approval, the attested checkout is refused with invalid_plan, before any transaction is recorded. The plan is fine; the transport went away. Relaunch with tunnel: true and run the same plan again.

Environment variables

SELF_AGENT_PAY_TUNNEL and the other settings.

Error codes

insecure_page, insecure_site, egress_lost, invalid_plan and the attested codes.