Egress firewall and request limits #
On this page
The egress firewall controls where your backend can send traffic and how much it can send. Request limits control incoming request sizes, duration, and rates. Read logs and counters says which log source holds the records of each.
Outbound network routes #
Application code reaches external services through the egress proxy. It reaches the platform's own endpoints directly. The network blocks other outbound connections; the client sees a connection timeout. Node.js Runtime lists the HTTP clients that use the proxy with no setup, and shows how a refused call reaches your code as an EgressRefusedError.
The proxy offers two ways to call an external service: the HTTPS tunnel and the gateway.
The HTTPS tunnel #
The backend opens an HTTPS connection through the proxy on port 443. The proxy carries it as a CONNECT tunnel, with no TLS or HTTP inspection.
- Allowed destinations. The manifest's
egresslist gives them as exact lowercase hostnames or patterns such as*.example.com. That pattern matches subdomains, notexample.comitself. Use a declared upstream for an external API's stored key: the gateway connects to that host, so it needs no entry inegress. For a client whose host is fixed in code you must not change, follow the binding exception and list that host inegressinstead. The list names only hosts the application's own process connects to. - Modes. Observe mode allows undeclared destinations; enforce mode refuses them.
- Addresses. The proxy pins each connection to the public address it resolved when the connection opened. Private, loopback, link-local (the cloud metadata address among them), reserved, and platform addresses are refused in both modes, whatever the
egresslist says. - Mail ports. Ports 25, 465, 587, and 2525 are outbound mail ports, refused like every port other than 443. Applications send no mail directly: send it through a mail provider's HTTPS API, declared as an upstream. An application can instead send an occasional request or notice through the platform's email service, with no provider of its own (Send email from your application).
- Metering. Each connection is metered when it closes: the host and port, the bytes each way, the duration, and the outcome. The record's byte count describes that connection; there is no monthly data-transfer allowance.
The gateway #
The backend calls /egress/v0/<upstream>/<path> on the platform's origin with its platform credential. The gateway adds the stored credential for the declared upstream and forwards the request, so the application never receives that credential.
A declared upstream's base URL cannot name an outbound mail port (25, 465, 587, or 2525). declare_outbound_api refuses it. The gateway also refuses calls to those ports. Send mail through a mail provider's HTTPS API, declared as an upstream. The platform's email service needs no upstream.
The platform credential is bound to one environment. The gateway reads the upstream's key at that environment's secret scope or at account scope, never from the other environment. A session or a minted token must name the environment in the header x-turnzero-cloud-environment. Without it the call is refused 400 environment_required. Under the platform credential, a header naming another environment is refused 403 environment_mismatch. Call an external API with an API key declares an upstream and calls it.
Platform endpoints #
The platform origin is https://turnzero.ai, which serves the storage, egress, and logging endpoints by path. Your code reaches the platform origin and declared platform service endpoints outside the proxy, and they need no entry in egress.
How the gateway handles a call #
A call to /egress/v0/<upstream>/<path> goes through these steps:
- The gateway reads the call's environment from the credential, or from the environment header under a minted token or a session, as The gateway describes.
- It refuses a base URL on one of the platform's own hosts, then looks up the declared host and refuses the call if any address it finds is not public. It connects only to the address it checked.
- It refuses calls to the application's own upstreams when the application reaches its daily byte limit. Calls to platform upstreams do not count toward that limit.
- Only then does it read the key stored under the declaration's credential name for that environment, or else at account scope, and never the other environment's.
- It puts the key in the declared header, removes the headers listed below from your request, and forwards it.
- It returns the upstream's status and body, streamed responses included, with the marker header
x-egress-upstream: <name>.
A refusal from the gateway itself, before the upstream is reached, uses the platform's error format without the marker header. A refusal that ends a stream already begun arrives as the final event egress_error inside the marked response. So handle a response that stops after streaming has begun.
Address and host checks #
At each call the gateway refuses, with status 403, a host that resolves to any private, loopback, link-local, reserved, or platform address. The refusal is one of egress_private_address, egress_loopback_address, egress_link_local_address, egress_reserved_address, or egress_platform_address. Its body gives the class and the host, not the address the host resolved to. The gateway refuses before it reads your key and before any request leaves it.
A host that resolves to no address is refused 502 upstream_unreachable, so an upstream on a private network cannot be reached through the gateway. A base URL whose host is a non-public IP address is refused at the declaration.
A base URL naming one of the platform's own hosts is refused 400 refused_platform_host, at the declaration and at each call. The platform's own hosts are its vaults, storage accounts, container registries, and service hostnames, and the management and sign-in endpoints of the cloud provider it runs on. Both hostnames of the issue service are among them, so an application reaches its own issue-tracking space only through the platform's issue-tracking upstream. The check is by name, never by the provider's domain, so your own vault, storage account, or registry at the same provider works like any other upstream.
What the upstream receives #
For an upstream you declare, /egress/v0/<upstream>/<path> becomes the declared base_url followed by /<path> and its query string. The gateway removes one trailing slash from base_url before joining them. It joins the path as received, keeping percent-encoded segments encoded instead of decoding and rebuilding them.
The upstream receives your request's method, path, query string, body, and headers, minus these:
| Removed | Why |
|---|---|
Your platform credential's Authorization header |
It is your credential to the platform, not to the upstream. The gateway removes it before applying the upstream's stored key. |
Host, Accept-Encoding, Content-Length, the hop-by-hop headers such as Connection, and every header your Connection header names |
The gateway sets them again for its own request. |
Expect |
The gateway responds to a 100-continue itself before it reads your body. A client that sends one before a large body, as curl does by default, works normally. |
| Any header you sent under the declaration's authentication header name | Only the stored key arrives under that name. |
Forwarded, Via, X-Real-IP, X-Client-IP, X-Cluster-Client-IP, True-Client-IP, X-Original-Forwarded-For, every header beginning x-forwarded- or x-envoy-, and the headers the hosting infrastructure's edge and ingress add |
The platform's edge or a proxy adds them on the way to the gateway. |
Every header beginning x-turnzero-cloud-, the environment header among them, and its legacy equivalents |
They are addressed to the platform. |
Every platform cookie in your Cookie header, including their legacy names. Its name begins turnzero_cloud_ in any letter case, with or without a __Host- or __Secure- prefix. |
They contain your own session on the platform or your end users' sessions on your application. |
These removals keep the platform's forwarding headers, internal identifiers, and session cookies out of the upstream request. A header you send under one of those names is removed too, because the edge adds to the value you sent. To pass a value such as an end user's address, use a header name that starts with a prefix naming your own application, for example x-myapp-end-user-address.
Every other header you send arrives unchanged, your own cookies included. Headers you do not send are filled with fixed defaults that identify nothing about you: Accept, Accept-Language, User-Agent, and Sec-Fetch-Mode.
What your code receives #
From the upstream's response, the gateway removes the header that the declaration's auth_header names, Set-Cookie, the hop-by-hop headers, Content-Encoding, and Content-Length. The body and the other headers pass through unchanged. The gateway adds x-egress-upstream with the upstream's name. An upstream that echoes the key in its response body returns it to your process, so declare only an upstream you trust with the key.
The gateway limits the request size, the response size, and the upstream's time. It refuses a request over its size limit 413 request_too_large, a response over its limit 502 response_too_large, and a slow upstream 504 upstream_timeout. A stream that passes a limit stops with that final event. No log source holds the gateway's record of each call.
Observe before enforce #
A new application begins in observe mode. The tunnel records each connection attempt and allows an undeclared destination that passes its other checks. Platform staff switch an application to enforce mode; you cannot switch it yourself. tzcloud_read_status reports the current mode as egress_mode.
In enforce mode the proxy refuses an undeclared destination with HTTP status 403 egress_undeclared. It records the host it refused and, for a hostname, the manifest edit that would allow it. A client that shows the proxy's response can also read its X-Egress-Refusal header; other clients may show only the status. Authentication, port rules, and address checks apply in both modes.
How an undeclared target is refused depends on its form:
- An address literal in a private, loopback, link-local, reserved, or platform range is refused by its address range in both modes. The refusal gives no manifest edit, because the
egresslist accepts no address literal. - A hostname is refused
egress_undeclaredin enforce mode before the proxy resolves it. In observe mode the proxy resolves it, and refuses it by address range if it resolves into one of those ranges.
Undeclared destinations in read_status #
read_status lists the undeclared destinations that the serving version reached in observe mode. Read it after a deploy to find the hostnames to declare before the application moves to enforce mode. The list is the egress member inside the response's application member. Where the version reached an undeclared destination, the response's summary gives their count and identifies that member. Where it reached none, the summary says nothing about egress. With brief: true, the member keeps only read and total; where total is above zero, read again without brief for the list.
Each entry gives the host and port, the number of connections, the time of the last one, and the remedy. For a hostname, the remedy is the manifest edit that declares it; for an address literal, it says to declare the hostname the address serves. An entry whose host is that of an upstream you declared also lists those upstreams. Your code called the host directly, so the gateway added no key, and the remedy names the upstream's gateway route, /egress/v0/<name>/. The read_status reference gives every member of the list.
The list covers the environment the response describes, from the later of two times: when its serving version started, or seven days before the read. since gives that start, or the oldest record read where the read stopped at its limit first. For anything before since, use read_logs with filter: "undeclared". The member's earlier says so in every whole response.
The list leaves out refused connections: refusals in enforce mode, refusals of an undeclared host by port or address range, and connections a client outside the proxy failed to open. It also leaves out a host that was declared when it was reached and has since been removed from the manifest. read_logs with filter: "undeclared" returns both kinds of record. A host the manifest now declares is dropped from the list.
Finding hostnames to declare #
filter: "declared" and filter: "undeclared" select recorded egress destinations against the current manifest. Use the undeclared list to find the hostnames to declare before platform staff switch the application to enforce mode.
- The filter reads the per-minute records of the
egressandharnesslog sources; with no source named, it reads both. - It leaves out platform endpoints, loopback targets, and the
harnessrecords of connections that went through the proxy. - It filters the records it retrieved and does not fetch older ones to fill the requested limit.
- An address literal in the
undeclaredresults is not a host to declare, because theegresslist accepts no address literal. Declare the hostname the address serves instead. - An address in a private, loopback, link-local, reserved, or platform range is refused by its range in enforce mode too.
When the control plane cannot be reached #
Each proxy replica caches an application's egress settings and mode for a short interval. While the control plane cannot be reached, a replica keeps its cached answer for up to an hour from its last successful read. A change such as an account suspension can then take effect late. Past that, or with no cached answer, it refuses new connections 503 egress_resolve_unavailable until the control plane responds again. Connections already open run to their own limits.
Outbound limits #
Both sizes have the same two outbound limits, shared by the application's environments: 1,200 new connections a UTC minute and 25 GB a UTC day.
- Connections per minute. The new connections the application opens through the HTTPS tunnel in one UTC minute. Gateway calls do not count toward it.
- Bytes per day. The bytes the application sends and receives in one UTC day, through the tunnel and through gateway calls to its own declared upstreams. Calls to the platform's own upstreams,
ai-allowanceandissue-tracking, do not count toward it.
The proxy runs one to three replicas, and each replica counts the minute's connections on its own. So an application whose connections spread over the replicas can open up to the limit through each one. The gateway keeps no count per minute. Its calls are limited instead by the platform's request limit per credential per minute, which refuses with HTTP 429 rate_capped.
The limits apply in observe and enforce mode alike. They limit traffic volume; destination checks apply separately. In enforce mode, an undeclared destination is still refused egress_undeclared first.
At the limit #
At either limit, the proxy refuses a new connection with HTTP 429: egress_connections_capped at the minute limit, and egress_daily_bytes_capped at the day limit. At the minute limit, connections already open keep running.
At the day limit, the proxy also cuts each open tunnel connection of the application at its next byte. It records the cut as refused_bounds in the connection's record under the egress source of read_logs, naming egress-bytes-per-day as the limit passed. Your client receives no refusal name for the cut. The gateway refuses calls to the application's own upstreams with HTTP 429 egress_daily_bytes_capped. A refused call reads no key and sends nothing.
Each refusal's body contains the count, the limit, and resets_at, the time the limit resets. Your code reads them in a gateway refusal, and in a proxy refusal where its client shows the proxy's response. A tunnel refusal reaches code that uses the platform's routed clients with the refusal's name and the status 429, without the three figures. The tunnel's record of the refusal, under the egress source of read_logs, contains all three.
The minute limit resets at the start of the next UTC minute, and the day limit at the start of the next UTC day.
Where the figures are read #
read_usage returns an egress_limits member for each application: the two limits, bytes_today, refused_today, a state of ok, capped, or unset, and resets_at. read_plan_quotas lists each size's two limits as egress-connections-per-minute and egress-bytes-per-day. Size and usage describes both actions.
Each size's two figures are set from the start. When platform staff clear a figure, that limit refuses nothing: read_plan_quotas then shows a null quantity, and egress_limits shows that limit as null. The platform counts the day's bytes either way. A changed figure applies on the gateway within a minute, and on the tunnel within a minute plus the proxy's usual cache interval.
How exact the limits are #
The daily limit is approximate. The total each check reads trails the traffic by up to a few reporting intervals, so an application can pass the limit by a margin before the refusals start. Calls already running when the limit is reached still complete, each up to the gateway's response size limit. A tunnel connection open across midnight UTC counts toward the day it opened. bytes_today in read_usage trails the traffic in the same way. If the gateway cannot read the day's figures, it allows calls without the day check for the next minute.
The execution window #
Each ordinary HTTP request has a time limit, the execution window. It is 180 seconds by default, one platform setting the same for every application, and a scheduled run has a longer window of its own. At the deadline the serving router responds with HTTP 504 window_ended if the response headers have not been sent; otherwise it cuts the streaming response. What an application must do on Node.js Runtime says how a handler meets the deadline, and what happens to a process whose handler does not stop.
The request size limit #
The serving router forwards a request body of up to 64 MiB, 67,108,864 bytes, to your application. It refuses a larger body with HTTP 413 request_too_large, naming the limit in bytes, and the request never reaches your application. The router answers this before any other check, so a refused request counts against no per-address or per-user limit.
A body sent with Content-Encoding gzip or deflate is decoded first, and the limit counts the decoded bytes. Your application receives the decoded body without the Content-Encoding header. A body in any content encoding but gzip, deflate, or identity is refused with HTTP 400 invalid_request, also before any other check.
This limit is the router's own. The gateway's limits above apply to your application's outbound calls, and a package such as Storage sets its own limit on the requests it serves.
The per-address and per-user limits #
The serving router limits how fast one client address, and one signed-in user, can reach your application. It keeps three counts per application, each per minute and per router replica:
- A request with no valid session counts against its client address, which allows 300 a minute.
- A request with a valid session, as the cookie or as a bearer token, counts against the user, who is allowed 300 a minute. It also counts against the address's signed-in count, which allows 30,000 a minute. It does not count against the address's anonymous count.
- An IPv6 client address counts as its /64 prefix, and the production and development hostnames share one count.
A request past any bound it counted against is refused with HTTP 429 rate_capped and a Retry-After header giving the seconds to the next minute. It never reaches your application. A bearer the router cannot verify counts once against the source address before it is refused (Verifying an end user).
The rate limits cover every request that would reach your application. They do not cover the web client's files the router answers from the platform's file store, the end-user sign-in routes under /__account/, the three well-known documents, or scheduled runs. A request for a client file that reaches your application, because the store did not answer it, counts like any other request.
The counts are kept per router replica, and the router runs at least three replicas. One client address whose requests spread over the replicas can therefore get up to 300 a minute through each, and more as the platform adds replicas. Many users behind one address, such as an office or a mobile carrier's gateway, share the address's counts. Each signed-in user among them has a count of their own, and the address allows a thousand signed-in users at thirty requests a minute each.
These rate limits slow individual sources. For each minute in which the bound refused requests, the router writes one source_refused record into your application's logs under the router source. The record gives the number of refusals under each of the three counts, the total, and the number of addresses refused. It never gives an address or a user.
WebSocket connections #
An application that declares websockets in its manifest accepts WebSocket upgrades on its hostnames. The upgrade request meets every check above but the size limit, since it carries no body, and it counts once in each per-address and per-user count. Once the application answers 101, the connection is outside the execution window, and the serving router bounds it instead. Limits and metering in Use WebSockets gives each figure and close code, and when the platform closes connections itself.
The platform request limit #
The platform also limits how fast one client address can call the platform itself: the Model Context Protocol (MCP) server, the management actions, the sign-in routes, and the pages of the site. This limit is separate from the limits above, which apply to your application.
Every request to the platform counts once, against one of these limits:
- A page view of the site or its documentation counts toward the address's page limit, 600 a minute. The stylesheet and the files under
/assets/do not count. - A read of the library over HTTP,
read_library, counts toward the address's library limit, 3,000 a minute. Taking a library entry reads its list and then each of its files, so one take makes many reads. - A signed-out call to
search_documentation, one that sends no token, counts toward the address's documentation search limit, 120 a minute. A signed-in search counts as any other management action does. - Every other request counts toward the address's request limit, 600 a minute:
/mcp, the other management actions, the context reads, and the sign-in routes. A dashboard page or the approval page counts there only while you are signed out. - A call to the storage, egress, logging, push, or email endpoints that presents a valid credential counts against that credential instead, 600 a minute. Applications behind one address therefore do not share a count there, and two credentials of one application are counted apart.
- A call to those endpoints with a credential the platform does not know, such as a revoked or mistyped one, returns 401. It counts toward a separate limit for the address, 600 a minute.
When a call with your application's credential exceeds this limit, the platform writes a rate_capped event to your application's logs, with source platform. Each copy of the platform's control service writes at most one such event per credential per minute.
The six limits are counted apart, so reading many pages, taking library entries, or searching the documentation does not use up the address's calls to /mcp. A request past a limit is refused with HTTP 429 rate_capped, before the platform reads the request's body, and a page view past it gets the same JSON response, not a page. The response has a Retry-After header giving the seconds to the next minute: wait that long, then repeat the request. People behind one address, such as an office, share that address's limits.
When the gateway is busy checking credentials #
On the storage, egress, logging, push, and email endpoints, the gateway checks each credential it is shown and keeps the answer for 30 seconds. Each gateway replica checks a limited number of new credentials a second. A call it cannot check within two seconds is refused with HTTP 503 credential_lookup_busy and a Retry-After header of 1. So can a call made while many new credentials wait, especially from one address. Nothing was done, so repeat the same call after one second. The refusal counts toward no limit on this page.
An upload or download grant is kept for those 30 seconds too, so a grant the platform ends, such as one whose application was deleted, can serve calls until they pass. The gateway still checks a grant's expiry, and an upload grant's one write, on every call.
The router mark #
The application is reachable through the serving router at <label>.ai.host for production, <label>-dev.ai.host for development, and any configured custom domains. Every application may attach one custom domain, a monthly item. Every response on the development hostname has the header X-Robots-Tag: noindex, nofollow. The serving router marks each request it forwards and sets its forwarded headers. A request that reaches the application's container by any other address, without that mark, is refused 403 router_mark_required before your own listener runs.
What the router sets on each request #
The serving router sets x-forwarded-host, x-forwarded-proto, x-forwarded-for, and x-request-id on every request it forwards. What the router sets on each request on Node.js Runtime says what each holds and how to build an absolute address from them.
Related #
- Call an external API with an API key declares an upstream and calls it through the gateway or the tunnel.
- Read logs and counters reads the records this page describes, and its step 4 says which source holds each.
- Size and usage reads the outbound limits and the day's figures.
- Use WebSockets declares WebSockets and gives the connection limits.
- Egress is the package page for the proxy and the gateway.
- Node.js Runtime describes the runtime harness in your process, the clients it routes, and the request time limit.
- A deployed app's settings lists
APP_PUBLIC_HOSTand the proxy settings. - The manifest describes the
egressmember and the other declarations. - read_logs is the action's generated reference entry.