QuotaGuard and Retool Integration Guide

QuotaGuard gives Retool applications a stable, static outbound IP address for requests that leave Retool and reach external services — things like third-party APIs, cloud databases behind security group rules, and partner services that require a pre-registered source address. QuotaGuard is not needed for internal Retool-to-Retool operations, Retool’s own built-in database, or Retool resource connections where the destination does not enforce IP allowlisting.

Why Retool Apps Need Static IPs

Retool Cloud runs on shared AWS infrastructure with dynamic outbound IPs. Retool does not publish these IPs or make them predictable — they can change at any time without notice.

This creates problems in the following scenarios:

• Database security groups — RDS, Cloud SQL, and other managed databases commonly restrict inbound connections to a list of trusted IP addresses. Retool’s dynamic IPs cannot maintain a stable entry on that list.
• MongoDB Atlas IP access controls — Atlas requires every connecting IP to be explicitly listed. Retool’s rotating addresses make that list impossible to maintain without disabling the control entirely.
• Enterprise APIs in finance, healthcare, and logistics — These APIs frequently require you to pre-register a source IP before issuing credentials. A changed IP causes the API to reject requests with a 403 or connection refusal.
• Partner APIs that use source IP as a second authentication factor — Payment processors, insurance carriers, and similar services treat an unrecognized source IP as an unauthorized caller.
• Corporate internal APIs behind firewalls — Firewalls that block unrecognized cloud IP ranges will drop requests from Retool’s shared infrastructure.

Retool does publish a broad list of shared IP ranges, and some teams add those ranges to database allowlists as a workaround. The problem: doing so opens access to every other Retool customer running on that same infrastructure. QuotaGuard provides two dedicated static IPs that belong exclusively to your account.

Deployment Type Determines Setup Method

How you integrate QuotaGuard with Retool depends on how Retool is deployed.

Why Retool Cloud requires a different approach: Retool Cloud does not expose the underlying server environment, so standard proxy environment variables cannot be set. The middleware pattern routes requests through a small service that you control, which sits between Retool and the destination API or database. From the destination’s perspective, the request arrives from a QuotaGuard static IP.

Self-hosted Retool runs in Docker or Kubernetes, where the container environment is fully accessible. Environment variables can be set directly on the Retool container, and all outbound traffic routes through the proxy without any middleware layer.

Getting Started

Create a QuotaGuard account at quotaguard.com. During setup, choose a proxy region closest to the external service you are connecting to — not closest to Retool’s infrastructure — because latency is determined by the hop from the proxy to the destination.

After account creation, your proxy URL will look like this:

http://username:password@us-east-static-01.quotaguard.com:9293

Your account includes two static IPs, both active simultaneously. Traffic is load-balanced across them — you cannot control which IP a given request uses. When submitting IPs to a firewall allowlist or database security group, always add both. They are listed in the QuotaGuard dashboard under your account overview.

Option A: Retool Cloud Setup (Middleware Pattern)

Because Retool Cloud does not expose server environment variables, the approach is to deploy a lightweight Node.js service on any platform that supports environment variables — Heroku, Render, Railway, Fly.io, or similar. Retool calls this middleware, the middleware forwards the request through QuotaGuard, and the response returns to Retool. From the destination API’s perspective, the request arrives from a QuotaGuard static IP.

Step 1: Deploy the Middleware

Create and deploy a Node.js/Express service with the following code:

import express from 'express';
import { HttpsProxyAgent } from 'https-proxy-agent';

const app = express();
app.use(express.json());

const proxyUrl = process.env.QUOTAGUARDSTATIC_URL;
const agent = new HttpsProxyAgent(proxyUrl);

app.post('/proxy', async (req, res) => {
  const { url, method = 'GET', headers = {}, body } = req.body;
  try {
    const response = await fetch(url, {
      method,
      headers,
      agent,
      body: body ? JSON.stringify(body) : undefined
    });
    const data = await response.json();
    res.json(data);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.listen(process.env.PORT || 3000);

Step 2: Set the Environment Variable

On the middleware host platform, set QUOTAGUARDSTATIC_URL to the full proxy URL from your QuotaGuard dashboard:

QUOTAGUARDSTATIC_URL=http://username:password@us-east-static-01.quotaguard.com:9293

Step 3: Create a Retool Resource

In Retool, create a REST API resource pointing at your middleware URL. When you build a query in Retool, send the target URL and any payload as the request body. The middleware forwards the request through QuotaGuard and returns the result.

Example request body from a Retool query:

{
  "url": "https://api.your-partner.com/endpoint",
  "method": "POST",
  "headers": { "Content-Type": "application/json" },
  "body": { "key": "value" }
}

Step 4: Verify

Create a Retool query against the middleware that calls https://ip.quotaguard.com:

{
  "url": "https://ip.quotaguard.com",
  "method": "GET"
}

The response should return one of the two static IPs from your QuotaGuard dashboard. Run the query a few times — both IPs should appear as the load balancer alternates between them.

Option B: Self-Hosted Retool Setup

Self-hosted Retool runs in Docker or Kubernetes, giving you direct access to the container environment. Set these environment variables in the Retool container configuration:

HTTP_PROXY=http://username:password@us-east-static-01.quotaguard.com:9293
HTTPS_PROXY=http://username:password@us-east-static-01.quotaguard.com:9293
QUOTAGUARDSTATIC_URL=http://username:password@us-east-static-01.quotaguard.com:9293

Docker Compose

Add the variables to the environment block of your Retool service:

services:
  retool:
    environment:
      HTTP_PROXY: "http://username:password@us-east-static-01.quotaguard.com:9293"
      HTTPS_PROXY: "http://username:password@us-east-static-01.quotaguard.com:9293"
      QUOTAGUARDSTATIC_URL: "http://username:password@us-east-static-01.quotaguard.com:9293"

Kubernetes

Add the variables to the env section of the Retool container in your deployment manifest:

env:
  - name: HTTP_PROXY
    value: "http://username:password@us-east-static-01.quotaguard.com:9293"
  - name: HTTPS_PROXY
    value: "http://username:password@us-east-static-01.quotaguard.com:9293"
  - name: QUOTAGUARDSTATIC_URL
    value: "http://username:password@us-east-static-01.quotaguard.com:9293"

Restart the Retool container after adding the variables. To verify, create a Retool REST API resource that queries https://ip.quotaguard.com directly. The response should match one of the two static IPs in the QuotaGuard dashboard.

Database Connections via QGTunnel

The HTTP proxy handles web requests — HTTP, HTTPS, and any protocol that rides over those. It does not help with raw TCP connections. If your Retool instance connects to PostgreSQL, MySQL, MongoDB (native driver), Redis, or any other database using a direct socket connection, the HTTP proxy does not apply.

QGTunnel applies to self-hosted Retool only. Retool Cloud connects to databases through Retool’s own database connector infrastructure — you cannot insert QGTunnel into that path. For Retool Cloud database connections that require a static IP, the middleware pattern (Option A) is the correct approach: route database queries through a middleware API rather than connecting directly from Retool. This works for HTTP-based database APIs such as MongoDB Atlas Data API, Supabase REST, and PlanetScale HTTP. It does not work for native TCP drivers.

Installing QGTunnel (Self-Hosted)

Add this to your Dockerfile to install the binary:

RUN curl https://s3.amazonaws.com/quotaguard/qgtunnel-latest.tar.gz | tar xz -C /app/bin

Configuring the Tunnel

In the QuotaGuard dashboard, go to Settings > Setup > Tunnel > Create Tunnel and enter the following:

Use the actual hostname and port for your database. Repeat for each database host if you have more than one.

Updating the Start Command

Wrap the Retool start command with qgtunnel:

/app/bin/qgtunnel node_modules/.bin/retool-start

With transparent mode enabled, your Retool instance connects to the database using the original hostname — exactly as configured. QGTunnel intercepts that connection and routes it through your QuotaGuard static IPs. From the database’s perspective, the connection arrives from one of those two IPs.

Add both static IPs to the database security group. Because traffic is load-balanced, either IP may be the source of any given connection.

QuotaGuard Shield: Static IPs for Inbound Retool Traffic

Everything above covers outbound traffic — requests Retool sends to external services. Shield addresses the opposite direction.

If a third-party service needs to send webhooks or data to a Retool-connected endpoint, and that service’s security team requires a fixed source IP for what they consider inbound traffic to their systems, Shield is the relevant product. This comes up in enterprise B2B integrations where a partner’s firewall must allowlist your server before their systems will accept data from it.

Shield provides stable IP addresses for that inbound path with SSL passthrough, so traffic is end-to-end encrypted and the proxy does not inspect the payload. It is appropriate for scenarios involving PHI, payment card data, or compliance frameworks that prohibit traffic inspection at intermediary services.

Learn more about QuotaGuard Shield →

Troubleshooting

Retool Cloud: IP still shows as Retool’s IP after middleware setup The middleware is not routing the request through the proxy agent. Confirm QUOTAGUARDSTATIC_URL is set on the middleware host and that the agent is being passed to the fetch call. Add a test endpoint to the middleware that calls https://ip.quotaguard.com directly and verify it returns a QuotaGuard IP before involving Retool at all.

Self-hosted: wrong IP after adding environment variables The container must be restarted after adding variables — they are not picked up by a running process. Confirm the variables are set inside the container:

docker exec retool-container env | grep PROXY

If the variables are absent, check that they are defined in the correct service block in your Compose file or deployment manifest.

407 Proxy Authentication Required The credentials in the proxy URL are incorrect. Copy the full URL directly from the QuotaGuard dashboard — do not retype it manually. The correct format is http://username:password@hostname:port, with a colon between username and password and an @ before the hostname.

Database connection still refused after QGTunnel setup Both static IPs must be in the database security group, not just one. Connections are load-balanced across the IP pair, so either address may be the source. Allowlisting only one IP causes roughly half of connection attempts to be refused.

Middleware returns timeout on database queries The middleware pattern works for HTTP/REST database APIs (MongoDB Atlas Data API, Supabase REST, PlanetScale HTTP). It is not suitable for native TCP database drivers. For those, use QGTunnel on self-hosted Retool — or consider migrating to an HTTP-based API layer in front of the database.

QuotaGuard Static vs QuotaGuard Shield

For most Retool use cases, Static is the right choice. Choose Shield when transmitting PHI, payment card data, or any data under a compliance framework that prohibits traffic inspection at intermediary services — the proxy provider must not be able to read the payload.

Ready to Get Started?

• Start a free QuotaGuard trial →
• Contact support if you have questions about your specific integration or need help choosing a plan.