Egress through a proxy

This guide is for platform operators whose cluster reaches the internet only through an HTTP or HTTPS proxy. It covers pointing the Arcade Engine at the proxy, which allowlists decide whether a call uses it, and what the proxy must allow so end users’ OAuth tokens keep renewing. Read it alongside Internal networking, which covers the same allowlists for internal destinations.

Point the Arcade Engine at the proxy

The Arcade Engine reads the standard proxy variables. Set them with engine.extraEnv:

engine:
  extraEnv:
    - name: HTTPS_PROXY
      value: http://proxy.corp.example.com:3128
    - name: HTTP_PROXY
      value: http://proxy.corp.example.com:3128
    - name: NO_PROXY
      value: arcade-worker-main,.svc,.cluster.local,10.0.0.0/8,localhost,127.0.0.1

NO_PROXY must name every in-cluster destination the way the Arcade Engine addresses it. A leading-dot entry such as .svc matches only names that end in it, so it doesn’t cover a bare Service name such as arcade-worker-main: list each bare name. A CIDR entry matches only URLs that use an IP address, not a name that resolves into the range. The Arcade Engine’s calls to the Coordinator never use the proxy.

With networkPolicy.enabled, add the proxy’s address to networkPolicy.egressCIDRs, or the chart’s egress policy blocks the connection to it.

Which calls use the proxy

The Arcade Engine guards destinations that tenants or MCP servers supply, so it doesn’t send every outbound call the same way. With the proxy variables set, a call to an external host that doesn’t match NO_PROXY uses the proxy when:

A call to a host that isn’t allowlisted by name goes through the Arcade Engine’s private-address guard, which connects directly and ignores HTTPS_PROXY. On a network where only the proxy reaches the internet, that call fails. CIDR entries don’t change this: they’re checked against the address the Arcade Engine connects to, so they never send a call through the proxy.

List each provider and MCP host by name:

engine:
  authSsrfAllowlist:
    - https://login.microsoftonline.com # exact scheme + host [+ port]
    - "*.okta.com" # any subdomain of the suffix
  ssrfAllowlist:
    - https://mcp.example.com # the remote MCP server
    - https://auth.example.com # the authorization server it names

For an MCP server added in the dashboard or API, allowlist both the server and its authorization server. For one declared in engine.yaml, allowlist its authorization server. The Arcade Engine discovers the authorization server from the MCP server’s metadata, then calls it for the token exchange and every renewal.

Allow the token endpoints on the proxy

The proxy must allow every endpoint the Arcade Engine calls to get and renew end-user tokens:

• For an auth provider, the token_request, refresh_request, and user_info_request endpoints in its configuration. Built-in providers list their defaults in the auth provider reference. Microsoft uses login.microsoftonline.com.
• For a remote MCP server, the server’s host and its authorization server’s host.

Be aware that the Arcade Engine reads the token endpoint’s answer to decide whether to ask the end user to authorize again. The proxy should pass the status, headers, and body through unchanged. A response the proxy writes itself is read as the provider’s: a 400 or 401 whose body names an OAuth error code reads as a refusal, and asks the end user to authorize again. See When token renewal fails.

Size the proxy for renewal bursts

The Arcade Engine renews a token when a tool call finds it expired, not in the background. An agent that runs for many users at once, such as a scheduled job, renews many tokens at the same moment, and each renewal can make up to three attempts. Size the proxy’s per-source connection and rate limits for that burst: every renewal comes from the Arcade Engine’s pods. Agent developers can spread the load too; see Agents that call tools for many users.

Common failures