custom-domains

Register and manage custom domains for IC canisters via DNS and the HTTP gateway API.

Updated Apr 3, 2026
One-click install
npx skills add https://github.com/phukrit7171/Relationship-Smart-Contract-ICP --skill custom-domains-phukrit7171
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: custom-domains
Source: https://github.com/phukrit7171/Relationship-Smart-Contract-ICP/tree/main/.agents/skills/custom-domains
Command: npx skills add https://github.com/phukrit7171/Relationship-Smart-Contract-ICP --skill custom-domains-phukrit7171

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Serving an Internet Computer canister under your own domain requires coordinating DNS records, a domain ownership file, and a registration REST API, and small misconfigurations silently break TLS provisioning or canister calls. ## Core Features & Use Cases - DNS Configuration Guidance: Provides the exact CNAME, TXT, and ACME challenge records needed, including apex-domain workarounds with ANAME/ALIAS records. - Registration Lifecycle Management: Covers validate, register, update, and delete operations against the icp.net/custom-domains/v1 REST API with curl commands and expected JSON responses. - Troubleshooting Playbook: Lists nine common failure modes such as stale ACME TXT records, duplicate _canister-id entries, and misconfigured HttpAgent hosts, each with a concrete fix. - Use Case: You deployed a React frontend canister and want it reachable at app.example.com with a valid TLS certificate while keeping Internet Identity principals stable across origins. ## Quick Start Ask the assistant to walk you through registering your custom domain for your deployed IC canister, starting with the DNS records and the .well-known/ic-domains file.

Frequently Asked Questions about custom-domains

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up a custom domain for an IC canister?

Add a CNAME to CUSTOM_DOMAIN.icp1.io, a TXT record on _canister-id with your canister ID, and a CNAME for _acme-challenge to icp2.io. Then serve /.well-known/ic-domains from your canister and call POST https://icp.net/custom-domains/v1/YOUR_DOMAIN to register.

What DNS records are needed for IC custom domains?

Three records are required: a CNAME pointing your domain to CUSTOM_DOMAIN.icp1.io, a TXT record on _canister-id.CUSTOM_DOMAIN containing the canister ID, and a CNAME on _acme-challenge.CUSTOM_DOMAIN pointing to _acme-challenge.CUSTOM_DOMAIN.icp2.io.

Can I use a custom domain on an apex domain like example.com?

Many DNS providers do not allow CNAME records on apex domains. Use your provider's ANAME or ALIAS record type (CNAME flattening) pointing to CUSTOM_DOMAIN.icp1.io, or use a subdomain such as www.example.com instead.

Why does custom domain registration fail on the Internet Computer?

Common causes include a missing _acme-challenge CNAME, duplicate _canister-id TXT records, a missing .well-known/ic-domains file, or SSL/TLS features from your DNS provider interfering with the ACME challenge. Run the /validate endpoint to identify the specific error.

Should HttpAgent host point to my custom domain?

No. The host is the API endpoint for canister calls, not your frontend's origin. Leave host unset so a recent @icp-sdk/core HttpAgent resolves to https://icp-api.io, or set it explicitly to that value; pointing it at your custom domain makes calls fail.

How do I move a custom domain to a different canister?

Update the _canister-id TXT record to the new canister ID, then call PATCH https://icp.net/custom-domains/v1/YOUR_DOMAIN to notify the service. Poll the GET endpoint until the registration status confirms the update.