Attaching Custom Domains

Attach a custom domain to a project so the deployed app serves traffic at your hostname instead of the default *.agentuity.run URL. The domain lives in agentuity.json. The CLI validates DNS at deploy time, and the platform issues a TLS certificate on the first request.

agentuity project add domain example.com
agentuity project domain check
agentuity deploy

These examples show agentuity ... for readability. If the CLI is project-local, run the same command through your package-manager exec wrapper, for example npx agentuity ..., bunx agentuity ..., pnpm exec agentuity ..., or yarn exec agentuity .... See Local versus global CLI for install and undo commands.

Add a Domain

agentuity project add domain writes the domain into deployment.domains and validates DNS before saving:

agentuity project add domain example.com
agentuity project add domain example.com --skip-validation
agentuity --dry-run project add domain example.com

--skip-validation writes the domain without checking DNS first. Use it when you intend to add the records after committing the change. --dry-run previews the file edit without writing.

After a successful add, agentuity.json contains:

{
  "deployment": {
    "domains": ["example.com"]
  }
}

You can also add domains by editing agentuity.json directly. Validation runs on the next deploy.

DNS Records

For each domain, point either a CNAME or an A record at the per-project ION host. The CLI prints the exact target after project add domain and again during deploy.

Use a CNAME when you can. The A-record path exists for apex domains where most DNS providers don't allow CNAMEs.

Validate DNS

agentuity project domain check
agentuity project domain check --domain example.com

project domain check requires a local agentuity.json and verifies each configured domain resolves to the right target. With no --domain flag it checks all of them.

DNS validation also runs as a deploy step before any environment sync or build:

• During project add domain, non-interactive runs fail when DNS is missing unless you pass --skip-validation.
• During deploy, the CLI shows the missing records and retries every 5 seconds until DNS resolves or the command is cancelled.

Run agentuity project domain check before CI deploys when DNS changes are part of the release. If DNS is intentionally incomplete for a deploy validation run, pass agentuity deploy --skip-dns-validation and verify the domain before sending traffic to it.

TLS Certificates

After a successful deploy, the CLI fires a HEAD request at each configured domain to nudge the platform's cert issuance. This is non-blocking: the deploy banner prints regardless, and certs also issue on the first real request from any client.

The first request after a fresh domain attach can take a few seconds while the cert provisions. Subsequent requests use the cached cert.

Custom Domains in the Deploy Banner

When a deployment has at least one custom domain configured, the deploy banner prints the custom URL and dashboard URL:

[OK] Your project was deployed!
 
Deployment: deploy_abc...
-> Deployment: https://example.com
-> Dashboard:  https://app.agentuity.com/r/deploy_abc...

The Agentuity-hosted URLs still exist, but the custom-domain banner focuses on the configured domain. agentuity --json project show <project-id> returns urls.custom, and agentuity cloud deployment show surfaces configured domains in the Domains and DNS Records fields.

Removing a Domain

The CLI does not have a domain remove subcommand today. Edit agentuity.json and delete the entry from deployment.domains, then redeploy:

# After editing agentuity.json
agentuity deploy

Removing a domain from agentuity.json does not delete DNS records you set. Clean those up at your DNS provider once the deploy with the new config is live.

Multiple Domains

deployment.domains accepts any number of domains. Each one is validated independently at deploy time and gets its own TLS cert. Use this for staging vs production hostnames on the same project, or for serving the same app at multiple brands.

{
  "deployment": {
    "domains": ["example.com", "www.example.com", "app.example.com"]
  }
}

Next Steps

• Deploy Framework Apps: the deploy flow that validates and serves your domain.
• Custom Domains in the CLI Reference: full DNS troubleshooting surface.
• Regions: the project region determines the ION host used in A-record DNS.