← Back to Dashboard

Domain & Deployment

Configure how your AgenticMail Enterprise instance is accessed on the internet — subdomains, custom domains, CORS, tunnels, and migration.

Table of Contents

Overview

For everyone: This page controls how people reach your AgenticMail dashboard. By default, it runs on your local machine (localhost). To let your team and agents access it from anywhere, you can set up a free subdomain (yourcompany.agenticmail.io), connect your own custom domain (agents.yourcompany.com), or deploy via a Cloudflare Tunnel.

For technical users: The Domain & Deployment page manages DNS registration/verification, subdomain allocation on agenticmail.io, CORS origin policies, Cloudflare Tunnel lifecycle, and deployment key issuance for disaster recovery. The page queries /domain/status, /domain/cors, and /tunnel/status on load and provides forms for domain registration, subdomain changes, and tunnel management.

How It Works

  1. Start locally — your instance runs on localhost after initial setup.
  2. Choose a URL strategy — free agenticmail.io subdomain, your own custom domain, or both.
  3. Expose to the internet — via Cloudflare Tunnel (recommended for local), VPS deployment, Docker, Railway, or Fly.io.
  4. Verify ownership — for custom domains, add DNS TXT records and verify.
  5. Share the URL — your team and agents connect via the configured domain.

Key Concepts

Domain Status States

StatusMeaning
verifiedDomain ownership confirmed. Ready for use.
pending_dnsWaiting for DNS records to propagate and verify.
not configuredNo custom domain set up.

Domain Types

TypeExampleDNS RecordNotes
Subdomainagents.yourcompany.comCNAMERecommended — easier setup, doesn't affect main site.
Root/Apexyourcompany.comA recordEntire domain dedicated to AgenticMail. Requires A record (most providers don't support CNAME at apex).

Current Deployment

Shows the URL you're currently accessing the dashboard from (window.location.origin). This is the URL your team uses. If it shows localhost, the instance is only accessible from your machine.

AgenticMail Subdomain

A free subdomain on agenticmail.io — for example, yourcompany.agenticmail.io. This gives you a public URL without needing your own domain.

Changing Your Subdomain

Click "Change" to update. Validation rules:

Warning: If you're currently accessing the dashboard from the subdomain URL, changing it will require you to update DNS records, bookmarks, agent configurations, and access the dashboard from the new URL. CORS origins are auto-updated.

Custom Domain

Use your own domain for a professional, branded deployment.

Setup Process

  1. Click "Add Custom Domain" — choose between subdomain or root domain type.
  2. Enter your domain — e.g., agents.yourcompany.com (just the domain, not a URL).
  3. Optionally add contact email — for domain-related notifications.
  4. Click Register — the system issues DNS challenge records.
  5. Add DNS records at your DNS provider (see DNS Verification below).
  6. Click "Verify DNS Now" — or wait for automatic verification.
Tip: Use a subdomain like agents.yourcompany.com instead of the root domain — it's easier to set up and doesn't affect your main website.

DNS Verification

After registering a domain, you need to add two DNS records:

Step 1: Ownership Verification (TXT Record)

FieldValue
TypeTXT
Host / Name_agenticmail-verify.yourdomain.com
ValueThe challenge string shown in the dashboard

Step 2: Route Traffic

For subdomains (CNAME):

FieldValue
TypeCNAME
Host / NameYour domain
Valueyoursubdomain.agenticmail.io or your server hostname

For root domains (A Record):

FieldValue
TypeA
Host / NameYour domain (or @)
ValueYour server's IP address
Tip: DNS changes can take up to 48 hours to propagate. Some providers (Cloudflare, Route 53) support CNAME flattening at the apex, which allows CNAME records on root domains.

Deploy to Production

The deployment section offers five methods to expose your local instance to the internet:

MethodDifficultyDescription
Cloudflare Tunnel RecommendedEasyKeep running locally, securely exposed via your domain. No port forwarding needed. Automatic HTTPS.
VPS / ServerEasyDeploy to DigitalOcean, Hetzner, AWS, or any Linux server.
DockerMediumRun as a Docker container on any host.
RailwayEasyOne-click deploy to Railway.app.
Fly.ioMediumDeploy to Fly.io edge network.

Cloudflare Tunnel

The recommended method. Your app stays on your machine; Cloudflare Tunnel creates a secure connection to their network. Steps:

  1. Install cloudflared — click "Install Cloudflared" or install manually.
  2. Login to Cloudflare — authenticate with your Cloudflare account.
  3. Create tunnel — specify the hostname and local port.
  4. Start tunnel — traffic flows securely from your domain to localhost.

CORS Configuration

CORS (Cross-Origin Resource Sharing) controls which websites can make API requests to your server.

CORS is auto-updated when you change your subdomain or custom domain. For manual control, go to Settings → Network & Firewall.

Warning: Open CORS in production is a security risk. Always configure allowed origins when deploying publicly.

Deployment Key

After registering a domain, a deployment key is shown once. This key is required to recover your domain if you migrate to a new server.

Danger: The deployment key is shown only once. Save it securely immediately. Without it, domain recovery requires manual intervention.

Recovery command:

npx @agenticmail/enterprise recover --domain your.domain.com

Migration

To move your entire deployment to a new machine:

  1. Copy ~/.agenticmail/.env from the old machine (contains DATABASE_URL, JWT_SECRET, VAULT_KEY, PORT).
  2. On the new machine: mkdir -p ~/.agenticmail
  3. Save the .env file to ~/.agenticmail/.env
  4. Copy ~/.agenticmail/branding/ folder if you have custom branding (logo, favicon, login background).
  5. Start the server: npx @agenticmail/enterprise@latest start
  6. If using Cloudflare Tunnel: cloudflared tunnel login on the new machine, then redeploy from the dashboard.
Important: Without the same VAULT_KEY, encrypted credentials (agent email passwords, API keys) cannot be decrypted. You would need to re-enter them.

CLI Commands

PurposeCommand
Initial setupnpx @agenticmail/enterprise setup
Start servernpx @agenticmail/enterprise start
Verify DNSnpx @agenticmail/enterprise verify-domain
Recover on new servernpx @agenticmail/enterprise recover --domain your.domain.com

Configuration & Setup

API Endpoints

MethodEndpointDescription
GET/domain/statusGet domain registration and verification status
POST/domain/registerRegister a new custom domain
POST/domain/changeChange to a different custom domain
POST/domain/verifyCheck DNS verification status
DELETE/domainRemove custom domain
POST/domain/subdomainSet/change agenticmail.io subdomain
GET/domain/corsGet CORS allowed origins
GET/tunnel/statusCloudflare Tunnel status
POST/tunnel/installInstall cloudflared
POST/tunnel/stopStop running tunnel

Environment Variables (.env)

VariablePurpose
DATABASE_URLDatabase connection — all data lives here
JWT_SECRETKeeps login sessions valid across restarts
AGENTICMAIL_VAULT_KEYDecrypts stored credentials
PORTServer port (default: 3200)
TRANSPORT_ENCRYPTION_KEYCustom key for API transport encryption. If not set, falls back to ENCRYPTION_KEY, then JWT_SECRET. Used to encrypt all API responses in transit (dashboard ↔ server).
ENCRYPTION_KEYGeneral-purpose encryption key. Used as fallback for transport encryption if TRANSPORT_ENCRYPTION_KEY is not set.
Transport Encryption: When enabled in Settings → Security, all API responses are encrypted client-side before transit. The encryption key is derived from TRANSPORT_ENCRYPTION_KEY → ENCRYPTION_KEY → JWT_SECRET (in order of priority). SSE/EventSource streams are excluded automatically since they cannot send custom headers.

Best Practices

Troubleshooting

DNS verification fails

DNS propagation can take up to 48 hours. Verify your records are correct with dig TXT _agenticmail-verify.yourdomain.com. Ensure there are no typos in the challenge value.

Subdomain change breaks access

After changing the subdomain, you must update DNS to point the new subdomain to your server, then access the dashboard from the new URL. The old URL will stop working.

Cloudflare Tunnel not connecting

Ensure cloudflared is installed and logged in (cloudflared tunnel login). Check that the configured port matches your server's actual port. Review cloudflared logs for errors.

CORS errors in browser console

Add your dashboard URL to the allowed origins in Settings → Network & Firewall. CORS is auto-updated when you change subdomain/domain, but manual additions may be needed for custom setups.

"Enter just the domain, not a URL" error

Don't include https:// — enter only the domain (e.g., agents.yourcompany.com).

Lost deployment key

If you've lost the deployment key and need to recover, contact support. As a workaround, you can remove the domain and re-register it, but you'll need to update DNS records again.

Vault — Credentials encrypted with VAULT_KEY are tied to your deployment. Users — User access requires a reachable deployment URL. Compliance — Domain and deployment changes are logged in audit reports.
AgenticMail Enterprise Documentation Report an issue