Skip to main content

Documentation Index

Fetch the complete documentation index at: https://paper.brimble.io/llms.txt

Use this file to discover all available pages before exploring further.

Every request to a Brimble-hosted project hits the edge first. The edge terminates TLS, routes to the right service, and adds a few headers your app can use. This page covers what happens between your users’ browsers and your code.

​
Request lifecycle

User
 │
 │  1. DNS resolves your-domain.com → Brimble edge
 ▼
Edge
 │  2. TLS handshake (Let's Encrypt cert)
 │  3. Hostname lookup → match to project
 │  4. Header injection
 ▼
Service
 │  5. Container handles request, returns response
 ▼
Edge
 │  6. Response sent back over the same TLS connection
 ▼
User
The edge is the only public entry point. Your service container has no public IP, all traffic must go through the edge.

​
Routing

Routing is hostname-based. Brimble looks at the Host header and matches it against:
  • <project-name>.brimble.app, the default URL for every project.
  • <project-name>-<environment>.brimble.app, Preview and other non-production environments.
  • Your custom domains, once verified.
If a hostname doesn’t match a known project, the edge returns a generic 404. Reserved hostnames (localhost, internal addresses) return a “not connected” page.

​
TLS

Every Brimble URL serves over HTTPS. The edge handles TLS termination, so your service speaks plain HTTP internally, you never need to configure certificates on your container. For default URLs (*.brimble.app), Brimble uses a wildcard certificate. For custom domains, Brimble issues a free certificate from Let’s Encrypt as soon as the domain points at the edge. Certificates renew automatically before expiry. If a custom domain’s certificate fails to issue, the most common cause is a CAA DNS record that doesn’t authorize Let’s Encrypt, see TLS troubleshooting.

​
Headers Brimble injects

The edge adds a small set of headers before forwarding the request:
HeaderValue
X-Forwarded-Protohttps (always, even if the original request hit http://)
X-Forwarded-ForThe client’s real IP
X-Real-IPThe client’s real IP
X-Brimble-HostThe hostname the request came in on
X-Brimble-IdA unique ID for this request, useful for log correlation
X-Brimble-Project-VersionAn ISO timestamp identifying the deployment serving this request
If your app is behind a framework that respects X-Forwarded-Proto (Express’s trust proxy, Django’s SECURE_PROXY_SSL_HEADER, Rails’s force_ssl), enable it so the framework knows requests are arriving over HTTPS.

​
Headers Brimble strips

A few headers used by frameworks for internal-only signaling are stripped at the edge so they can’t be set by an attacker:
  • X-Middleware-Subrequest
  • X-React-Router-Prerender-Data
  • X-React-Router-SPA-Mode
Your code can set these on responses; they just won’t be honored if a client sends them.

​
WebSockets

WebSockets work without configuration. Any path with an Upgrade: websocket request header is upgraded transparently. Brimble keeps the connection open as long as both ends do. Common patterns it recognizes: /ws/*, /socket.io/*, anything that sends a proper upgrade.

​
HTTP/2 and gRPC

The edge speaks HTTP/2 to clients by default. Inside, it forwards using whatever transport the service expects:
  • HTTP/1.1 for normal services.
  • HTTP/2 cleartext (h2c) for gRPC services. Detected automatically when the request’s Content-Type starts with application/grpc.
gRPC and gRPC-Web both work. Bidirectional streaming, server streaming, and client streaming are all supported.

​
Rate limits

Public traffic to your project goes through Cloudflare, which rate-limits abusive single-source traffic at the edge before it reaches Brimble’s gateway. Throttled requests get 429 Too Many Requests from Cloudflare; normal user traffic is unaffected. Service-to-service calls inside Brimble’s network don’t go through Cloudflare and aren’t rate-limited. For workloads that need custom rules (high-traffic public APIs, large file ingest), contact support. See Rate limits for the full breakdown.

​
Body size

Request bodies are capped at 5 MB by default. JSON, form, URL-encoded, and binary uploads above 5 MB are rejected with 413 Payload Too Large. For larger uploads (file uploads, large data ingest), upload directly to object storage from the client and have your service handle the resulting key, rather than streaming through the edge.

​
Health checks

Brimble probes your service after deployment to decide whether traffic should flow to the new version:
  • Web services. A GET request to healthCheckPath (default /). Anything in the 2xx or 3xx range counts as healthy.
  • Workers. Process liveness only, if the process is alive, the worker is healthy.
  • Static sites. No probe; the artifact is served directly.
You can change the health check path under Settings → Configuration. Use a lightweight endpoint that doesn’t depend on slow downstream services, GET /healthz is a common pattern. If a deployment fails its health check repeatedly, it’s marked degraded. Traffic continues to flow to the previous active deployment.

​
Connection retries

By default a project runs as a single container, and the edge sends all of its traffic to that one. A single connection-level retry happens automatically if the container is briefly unavailable (between health-check passes during a deploy, for example). Application-level errors, a 5xx response your code returned, go straight to the client; the edge doesn’t retry those. If you’ve configured an autoscaling group and the project is running multiple containers, the edge distributes traffic across them and retries connection-level failures against another container before failing the request.

​
Outbound traffic

Your service can make outbound HTTP(S) requests freely. There’s no egress whitelist for normal traffic. Outbound traffic from a Brimble service appears to come from a region-specific IP range. If you’re whitelisting Brimble at a third-party API, get the current ranges from support, they aren’t fixed forever.

​
Next steps

Last modified on May 10, 2026