Skip to content

docs(custom-domains): name the ordering trap in the II pitfall #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marc0olo merged 1 commit into from
Aug 10, 2026
Merged

docs(custom-domains): name the ordering trap in the II pitfall #341

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions evaluations/custom-domains.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
{
"skill": "custom-domains",
"description": "Evaluation cases for the custom-domains skill. Tests whether agents produce correct DNS records, use the right registration API endpoints, and warn about common pitfalls like provider SSL interference and stale ACME records.",

"output_evals": [
{
"name": "DNS record configuration",
Expand Down Expand Up @@ -77,9 +76,18 @@
"Uses DELETE https://icp.net/custom-domains/v1/DOMAIN to notify the service",
"Does NOT suggest only removing DNS records without calling the API"
]
},
{
"name": "Adversarial: custom domain on an app that already has II users",
"prompt": "My IC app already has a few hundred users signed in with Internet Identity at its canister URL. I am about to point a custom domain at it. Anything I should watch out for? Short answer.",
"expected_behaviors": [
"Warns that II principals are per-origin, so existing users would get brand-new accounts at the custom domain",
"Says to pin the canister address as the derivation origin and list the custom domain in .well-known/ii-alternative-origins BEFORE the domain goes live",
"Notes that a domain which has already collected sign-ins cannot be repointed without orphaning those accounts",
"Does NOT present the custom domain switch as principal-neutral or a pure DNS change"
]
}
],

"trigger_evals": {
"description": "Queries to test whether the skill activates correctly.",
"should_trigger": [
Expand Down
2 changes: 1 addition & 1 deletion skills/custom-domains/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Custom domains work at the boundary node level — they map a domain to any cani

8. **Setting `HttpAgent`'s `host` to your custom domain.** `host` is the **API endpoint** canister calls go to, not the domain your frontend is served from. Your custom domain is the HTTP gateway — it does not serve `/api/v2`, so pointing `host` at it (or at `window.location.origin`) makes calls fail. You do not need to set `host`: a recent `@icp-sdk/core` `HttpAgent` resolves an omitted `host` to `https://icp-api.io` (the mainnet API boundary nodes) on a custom domain. Leave it unset, or set it explicitly to `https://icp-api.io` — never the gateway domain.

9. **Forgetting alternative origins for Internet Identity.** II principals depend on the origin domain. Switching from a canister URL to a custom domain changes principals. Configure `.well-known/ii-alternative-origins` to keep the same principals. See the `internet-identity` skill.
9. **Adding a custom domain to an app that already has users.** II principals are per-origin, so the new domain hands every returning user a brand-new account. Pin a derivation origin — the canister address, which a custom domain can never displace — and list the domain in `.well-known/ii-alternative-origins` **before** the domain goes live. A domain that has already collected sign-ins cannot be repointed without orphaning those accounts. See the `internet-identity` skill.

## Implementation

Expand Down
Loading