Set up a custom domain

Serve your TaskJuice workspace at a hostname you control, like automations.agency.com, with automatic TLS.

What a custom domain gives you

Every agency has a permanent URL at {slug}.taskjuice.ai. A custom domain adds a second hostname (for example, automations.agency.com) that keeps your brand in the address bar for sign-in, workflows, and every page your clients see.

The permanent URL never goes away. If DNS takes time to propagate, if a record expires, or if you remove the custom domain later, your team and your clients can still reach the app at {slug}.taskjuice.ai.

Who can do this

You must be a tenant admin on the agency. Editors and viewers cannot add or remove custom domains.

Before you start

You need a domain you control (you can add records at its DNS provider).
Use a subdomain like app.agency.com or automations.agency.com. Apex domains (agency.com) are not supported because a CNAME at the apex conflicts with email MX records.
One custom domain per agency. To change hosts later, remove the existing one first.

Step 1: Enter your hostname

Open domain settings
Sign in to your agency and go to Settings → Domain, or visit /settings/domain directly from any page.
Add your hostname
Type the full hostname (for example, automations.agency.com) into the Hostname field and click Add domain. The page switches to a guided card that shows you the exact DNS records to add.

Nothing is routing yet. Adding the domain just registers your claim and generates the ownership token you'll prove in the next step.

Step 2: Prove ownership with a TXT record

The guided card shows you a single TXT record. Copy both values into your DNS provider's zone for the domain.

Host:  _taskjuice-verify.automations.agency.com
Type:  TXT
Value: a4f9e2d1-5c3b-4e87-9d21-1f8c7e2b3a9f   (your actual token will differ)

TaskJuice checks for this record every 5 minutes. Once the record resolves and the value matches, the first step on the guided card flips to a green check.

How long DNS takes

Most providers propagate changes in under five minutes. A few are slower — Cloudflare is typically instant, Route 53 is within a minute, GoDaddy and Namecheap can take 15-30 minutes. If you're past 30 minutes with no green check, see Troubleshooting below.

Step 3: Point traffic with a CNAME record

Once ownership is proven, the guided card reveals a second record — the CNAME that actually routes traffic to TaskJuice.

Host:  automations.agency.com
Type:  CNAME
Value: <shown in the guided card>

Add this record alongside the TXT record. Do not remove the TXT record — TaskJuice re-checks it periodically and a domain whose ownership lapses will be flagged as unreachable.

Step 4: Wait for the certificate

As soon as the CNAME resolves, TaskJuice requests a TLS certificate for your hostname and installs it automatically. No action required. The guided card's third step shows a loading state, then flips to green with the date it activated. Most certificates issue within five minutes.

When the card shows Active, open https://automations.agency.com in a new tab. You should land on your TaskJuice workspace with a valid TLS certificate.

How often we recheck

Active domains are re-verified every 15 minutes. Pending or failed domains are checked every 5 minutes. This means if you fix a broken DNS record, it flips back to active within one check window, not overnight.

Fix a dns_failed or ssl_failed domain

When a previously active domain stops resolving or its certificate can't renew, the status card switches to red and a banner appears on every page of your workspace. Your permanent URL still works; only clients using the custom hostname are affected.

Confirm the DNS records at your provider
Open your DNS provider and verify both the TXT and CNAME records are still present with the exact values from the domain settings page. A common cause is a provider's auto-cleanup or a migration that silently drops older records.
Re-check without waiting for the cron
On the status card, click Recheck now. TaskJuice queues an immediate verification instead of waiting for the next 5-minute window. This button is rate-limited to one call every 30 seconds per agency.
If the records look right but still fail
Wait for DNS caches at your provider to expire. TTL on your records controls this — most providers use 300-3600 seconds. Rechecking won't help until the cached miss times out.

Auto-removal after 30 days

A domain stuck in dns_failed or ssl_failed for more than 30 days is automatically removed. Your permanent URL keeps working, but to restore the custom hostname you will need to add it again from step 1. The settings page and reminder emails surface the exact date two weeks before auto-removal.

Remove a custom domain

Click Remove domain on the status card and confirm. Clients using the custom hostname will stop reaching your workspace within 15 minutes as DNS caches expire. Your permanent URL is unaffected.

After removal, you can add the same hostname or a different one from the empty-state card.

Troubleshooting

The TXT record doesn't verify after 30+ minutes. Confirm the record name includes the _taskjuice-verify. prefix — some DNS provider UIs quietly strip leading underscores. Also confirm your provider added the record at the apex of the correct zone. If you added it to a different zone (for example, _taskjuice-verify.automations.agency.com in the agency.com zone instead of a delegated automations.agency.com zone), the lookup won't resolve.

The CNAME doesn't activate the domain. CNAME records can only be added at subdomains, never at the apex. If your DNS provider shows an error like "CNAME conflicts with SOA record," you're trying to add it at the root of the zone. Use a subdomain like app.agency.com.

The certificate is stuck issuing. Issuing requires the CNAME to resolve first. If the traffic CNAME isn't in place, or points at an old value, the certificate can't complete. Confirm the CNAME value matches exactly what the guided card shows — TaskJuice rotates it rarely, but if you copied the value before ownership was proven, re-check the card.

The domain auto-removed before I could fix it. Abandoned domains (stuck in pending for 14 days) or long-failed domains (stuck in failed for 30 days) are cleaned up automatically. To restore, add the domain again from /settings/domain. All DNS records need to be re-added because the ownership token regenerates on each add.

What a custom domain does not change

Your permanent subdomain. {slug}.taskjuice.ai stays live forever.
Webhook URLs. Webhook triggers continue to accept traffic at api.taskjuice.ai. End clients paste these URLs into third-party dashboards where branding rarely matters, so they stay on the canonical host.
Your admin login. The Payload admin UI at taskjuice.ai/admin is super-admin only and is never exposed on a custom domain.
Email sender addresses. Transactional email continues to come from a @taskjuice.ai address. White-label sender domains are a separate feature.

Next steps

Review Branding settings to match the app's colors and logo to your agency's brand.
If you haven't connected a first integration yet, see the Quickstart.