# How to Set Up Custom Domains for Retool Apps

- Tool: Retool
- Difficulty: Intermediate
- Time required: 20-30 min (plus DNS propagation wait time)
- Compatibility: Retool Cloud and Self-hosted
- Last updated: March 2026

## TL;DR

For Retool Cloud: go to Settings → Custom Domain, enter your domain, copy the CNAME target Retool provides, add a CNAME record at your DNS registrar, and Retool automatically provisions an SSL certificate. DNS propagation takes 1-48 hours. For self-hosted Retool, configure nginx as a reverse proxy in front of your Retool container with Let's Encrypt SSL via Certbot or the https-portal Docker image.

## Custom Domains for Retool Cloud and Self-Hosted

By default, Retool Cloud apps are served from yourorg.retool.com. Custom domains let you serve apps from tools.yourcompany.com or internal.yourcompany.com — a much more professional experience for teams and external stakeholders.

For Retool Cloud, the process is: configure the domain in Retool Settings, add a CNAME DNS record pointing to Retool's servers, and SSL is automatically provisioned. The entire setup takes about 15 minutes of work, with DNS propagation adding 1-48 hours of wait time.

For self-hosted Retool (Docker on AWS/GCP/Azure/on-prem), you configure an nginx reverse proxy or a load balancer in front of the Retool container, which handles SSL termination and domain routing. This tutorial covers both approaches.

## Before you start

- Access to your domain registrar's DNS management panel (Cloudflare, GoDaddy, Route 53, etc.)
- Admin access to your Retool organization
- A domain or subdomain to use (e.g., tools.yourcompany.com)
- For self-hosted: access to your Retool server and ability to configure nginx or a load balancer

## Step-by-step guide

### 1. Add the custom domain in Retool Settings (Cloud)

For Retool Cloud, go to Settings (top-right user menu) → Custom Domain (or Domain Settings). Click 'Add Custom Domain' or 'Configure Custom Domain'. Enter your desired domain or subdomain (e.g., tools.yourcompany.com). Do NOT enter 'https://' or a path — just the domain name.

Retool displays a CNAME target for you to add at your DNS registrar. Copy this value exactly — it will look something like: abc123.retool.com or yourorg.custom.retool.com.

**Expected result:** Retool displays the CNAME target value you need to configure at your DNS registrar.

### 2. Create the CNAME DNS record at your registrar

Log in to your domain registrar or DNS provider (Cloudflare, GoDaddy, Namecheap, AWS Route 53, Google Domains, etc.). Navigate to the DNS management section for your domain. Create a new DNS record:

- Type: CNAME
- Name/Host: tools (the subdomain prefix, without the root domain)
- Value/Points to: the CNAME target Retool gave you (e.g., abc123.retool.com)
- TTL: 3600 (or use your registrar's default)

For Cloudflare users: set Proxy status to DNS only (gray cloud, not orange) initially — orange-cloud proxying can interfere with Retool's SSL certificate provisioning.

```
# Example DNS record configuration (varies by registrar UI):
# Type: CNAME
# Name: tools
# Value: abc123.retool.com
# TTL: 3600 (1 hour)

# For AWS Route 53:
# Record type: CNAME
# Record name: tools.yourcompany.com
# Value: abc123.retool.com
# TTL: 300

# Verify DNS propagation (run in terminal or use online tools):
# dig CNAME tools.yourcompany.com
# Expected output: tools.yourcompany.com CNAME abc123.retool.com
```

**Expected result:** The CNAME record is saved in your DNS provider. Changes propagate within minutes to hours depending on TTL settings.

### 3. Verify SSL certificate provisioning

After DNS propagates, Retool Cloud automatically provisions an SSL/TLS certificate for your custom domain via Let's Encrypt. This takes a few minutes after DNS is verified. In Retool Settings → Custom Domain, the status changes from 'Pending DNS Verification' to 'Active' once complete.

If SSL provisioning fails: check that DNS has fully propagated (use dnschecker.org), verify the CNAME points exactly to Retool's target, and ensure no CAA DNS records block Let's Encrypt from issuing certificates for your domain.

```
# Check for CAA records that might block SSL:
# dig CAA yourcompany.com

# If you see a CAA record like:
# yourcompany.com CAA 0 issue "sectigo.com"
# You need to add Let's Encrypt to the allowed issuers:
# yourcompany.com CAA 0 issue "letsencrypt.org"

# Verify HTTPS is working after certificate provisioning:
# curl -I https://tools.yourcompany.com
# Expected: HTTP/2 200 (not SSL error)
```

**Expected result:** The custom domain status shows 'Active' in Retool Settings. Navigating to https://tools.yourcompany.com loads the Retool app login page.

### 4. Configure nginx reverse proxy for self-hosted Retool

For self-hosted Retool (Docker), configure nginx in front of the Retool container to handle SSL and domain routing. Below is a production-ready nginx configuration. SSL certificates are obtained via Certbot (Let's Encrypt).

First, install nginx and Certbot on your server. Then create the nginx configuration:

```
# /etc/nginx/sites-available/retool

server {
    listen 80;
    server_name tools.yourcompany.com;
    
    # Redirect HTTP to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name tools.yourcompany.com;
    
    # SSL certificates from Let's Encrypt
    ssl_certificate /etc/letsencrypt/live/tools.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tools.yourcompany.com/privkey.pem;
    
    # Modern SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    
    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options SAMEORIGIN;
    
    # Proxy to Retool container
    location / {
        proxy_pass http://localhost:3000; # Retool's default port
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400; # 24h for long-running operations
    }
}
```

**Expected result:** nginx proxies HTTPS traffic to the Retool container. Self-hosted Retool is accessible at https://tools.yourcompany.com.

### 5. Use https-portal for zero-config SSL on Docker (alternative)

For Docker-based self-hosted Retool, https-portal is the easiest SSL solution. Add it to your docker-compose.yml as a reverse proxy container. It handles Let's Encrypt certificate provisioning and renewal automatically.

```
# docker-compose.yml addition:
# (Add to your existing Retool docker-compose)

services:
  https-portal:
    image: steveltn/https-portal:1
    ports:
      - '80:80'
      - '443:443'
    environment:
      DOMAINS: 'tools.yourcompany.com -> http://retool:3000'
      STAGE: 'production'  # Use 'local' for testing, 'production' for Let's Encrypt
      # FORCE_RENEW: 'true'  # Uncomment to force certificate renewal
    volumes:
      - https-portal-data:/var/lib/https-portal
    depends_on:
      - retool
    restart: always

volumes:
  https-portal-data:

# Note: In STAGE: 'production', Let's Encrypt rate limits apply.
# Use STAGE: 'staging' first to test the setup without hitting rate limits.
```

**Expected result:** https-portal automatically provisions SSL certificates and proxies traffic to Retool. No manual nginx/Certbot configuration needed.

### 6. Update Retool configuration to use the custom domain

For self-hosted Retool, update the BASE_DOMAIN environment variable in your Retool configuration to match the custom domain. This ensures OAuth redirects, email links, and internal Retool URLs use the correct domain.

Update your docker-compose.yml or .env file:

```
# In Retool's .env or docker-compose.yml environment section:
BASE_DOMAIN=tools.yourcompany.com
COOKIE_INSECURE=false  # Set to false when using HTTPS

# If using OAuth (Google, GitHub, etc.) for Retool login,
# update your OAuth app's authorized redirect URIs to include:
# https://tools.yourcompany.com/oauth/callback

# Restart Retool after changing BASE_DOMAIN:
# docker-compose down && docker-compose up -d
```

**Expected result:** Retool generates correct absolute URLs using the custom domain in all system communications.

## Complete code example

File: `nginx/retool.conf (production configuration)`

```nginx
# Retool nginx Reverse Proxy Configuration
# Place in /etc/nginx/sites-available/retool
# Enable with: ln -s /etc/nginx/sites-available/retool /etc/nginx/sites-enabled/
# Get SSL cert: certbot --nginx -d tools.yourcompany.com

# Redirect all HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name tools.yourcompany.com;
    return 301 https://$host$request_uri;
}

# Main HTTPS server block
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name tools.yourcompany.com;
    
    # SSL (managed by Certbot)
    ssl_certificate /etc/letsencrypt/live/tools.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tools.yourcompany.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    
    # Security headers
    add_header Strict-Transport-Security "max-age=63072000" always;
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options SAMEORIGIN;
    add_header Referrer-Policy strict-origin-when-cross-origin;
    
    # Client body size (for file uploads)
    client_max_body_size 50M;
    
    # Proxy settings
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}
```

## Common mistakes

- **Setting a CNAME record on the apex/bare domain (yourcompany.com) which doesn't work with CNAME records in most DNS providers** — undefined Fix: Use a subdomain: tools.yourcompany.com, retool.yourcompany.com, or internal.yourcompany.com. If you must use an apex domain, switch to a DNS provider that supports ALIAS/ANAME records for CNAME-like behavior on apex domains (Cloudflare, Route 53, DNSimple).
- **Enabling Cloudflare proxy (orange cloud) immediately, which can interfere with Let's Encrypt SSL certificate provisioning** — undefined Fix: Set the Cloudflare proxy to DNS Only (gray cloud) during initial setup and SSL certificate provisioning. Once the custom domain shows as Active in Retool Settings and HTTPS works, you can optionally enable the Cloudflare proxy for additional DDoS protection.
- **Forgetting to update OAuth redirect URIs after setting up the custom domain, causing SSO login to fail** — undefined Fix: In your identity provider (Google Workspace, Okta, GitHub OAuth app), add the new custom domain URL to the list of authorized redirect URIs: https://tools.yourcompany.com/oauth/callback. The old yourorg.retool.com callback may still work, but new sessions from the custom domain URL will fail until this is updated.

## Best practices

- Use a subdomain (tools.yourcompany.com) rather than an apex domain — CNAME records are not supported on apex domains by most DNS providers
- Set DNS TTL to 300 (5 minutes) before making the switch so you can revert quickly if something goes wrong, then increase it after verification
- For Cloudflare users, set the CNAME proxy status to DNS only (gray cloud) during initial setup to allow Retool's SSL verification to work
- Test the custom domain in a fresh browser tab (without existing Retool session cookies) to verify the full login flow works correctly
- Update OAuth provider redirect URIs (Google, GitHub, Okta) to include the new custom domain URL before switching users over
- Monitor SSL certificate expiry — Let's Encrypt certificates expire every 90 days. Certbot auto-renewal should be configured, and https-portal handles renewal automatically
- Keep the original yourorg.retool.com URL working during transition — don't remove it until all users have switched bookmarks

## Frequently asked questions

### How long does it take for a custom domain to work in Retool after adding the DNS record?

DNS propagation typically takes 1-48 hours, depending on your DNS provider's TTL settings and global propagation speed. Cloudflare DNS typically propagates in minutes. After DNS propagates, Retool automatically provisions an SSL certificate which takes an additional 5-15 minutes. Use dnschecker.org to monitor propagation progress across different global regions.

### Can I use the same custom domain for multiple Retool apps?

A custom domain in Retool Cloud routes to your entire Retool organization, not a single app. All apps in your organization are accessible under the custom domain (tools.yourcompany.com/retoolApp/appName). You cannot route different subdomains to different individual apps within one Retool organization without additional infrastructure. However, each Retool organization can have its own custom domain.

### Do I need a paid Retool plan to use a custom domain?

Custom domain support is available on Retool's paid plans (Team plan and above). The free plan uses yourorg.retool.com without custom domain support. Check Retool's current pricing page for the exact plan tier that includes custom domains, as this can change with plan restructuring.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-set-up-custom-domains-for-retool-apps
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-set-up-custom-domains-for-retool-apps