Custom Domains

Verified and Pro users can use their own domain as the vanity URL prefix.

Prerequisites

• A Verified or Pro account (run gvu auth bind <email> to upgrade)
• A domain you control with DNS management access
• gvu CLI installed — see Quick Start (Windows: use WSL/WSL2 or download .exe)

Setup

Important: DNS must be configured before running gvu add. The server verifies your domain’s CNAME record during route creation.

1. Configure DNS

Point your domain to the service via CNAME:

go.yourcompany.com  CNAME  gomodvanityurls.com

2. Wait for DNS propagation

DNS changes typically propagate within seconds to a few minutes. You can verify with:

dig go.yourcompany.com CNAME +short
# Expected output: gomodvanityurls.com.

3. Add a custom domain route

gvu add go.yourcompany.com/private-module https://github.com/yourorg/private-module.git

The server verifies the CNAME record. If DNS is not yet configured, you will receive a DNS_NOT_CONFIGURED error — wait for propagation and try again.

4. TLS auto-provisions

TLS certificates are provisioned automatically via Caddy On-Demand TLS. The CLI probes the route after creation and warns you if TLS is still provisioning.

5. Use it

import "go.yourcompany.com/private-module"

Quota

Custom domain routes share the same quota pool as gomod.io routes. For example, a Verified user with 3 custom domain routes has 7 remaining slots for gomod.io routes.

Domain Binding (Pro only)

For Pro users, when you add your first route under a custom domain, that domain is automatically bound to your account. Only you can add routes under that domain afterwards. This prevents other users from using your DNS configuration.

Note: Deleting all routes under a domain does not release the binding. Contact support if you need to release a domain binding.

Tips

• Use a subdomain like go.yourcompany.com or pkg.yourcompany.com
• Custom domain routes are exempt from the short path restriction
• You can mix gomod.io and custom domain routes in the same account
• Different subdomains are independent — go.example.com and pkg.example.com can belong to different users
• Domain binding persists even after Pro subscription expires or all routes are removed
• --subdir works with custom domains too:

  gvu add go.mycompany.com/module-a https://github.com/myorg/monorepo.git --subdir go/module-a
  

Wildcard Routing (Pro only)

Pro users can create wildcard routes that cover all repos under a custom domain prefix, eliminating the need to add routes one by one.

See Wildcard Routing for details, priority rules, and examples.