Skip to main content
Reserve a free *.uncld.dev subdomain for your cluster. This domain is automatically managed and points to your cluster machines running Caddy.

​
Usage

uc dns reserve [flags]

​
Flags

​
--endpoint
string
default:"https://dns.uncloud.run/v1"
API endpoint for the Uncloud DNS service.

​
Examples

​
Reserve a domain

uc dns reserve
Output: 
Reserved cluster domain: abc123.uncld.dev

Updated DNS records for abc123.uncld.dev

​
What Happens

  1. Domain Allocation - Uncloud DNS assigns you a unique subdomain like abc123.uncld.dev
  2. DNS Records - If Caddy is deployed, A/AAAA records are automatically created pointing to machines with public IPs
  3. Service Hostnames - Your services become accessible at service-name.abc123.uncld.dev

​
Using Your Domain

Once reserved, services are automatically available on your domain: 
uc run nginx:latest -p 80/https -n web
Your service is now accessible at:
  • https://web.abc123.uncld.dev
If you don’t specify a service name, a random one is generated: 
uc run nginx:latest -p 80/https
# Accessible at https://random-name.abc123.uncld.dev

​
Custom Hostnames

You can still use custom hostnames: 
uc run myapp:latest -p app.example.com:8080/https
But you’ll need to configure your DNS to point to your cluster.

​
Automatic DNS Updates

When you:
  • Add a machine to the cluster
  • Remove a machine
  • Update a machine’s public IP
Uncloud automatically updates DNS records to point to all machines running Caddy.

​
Caddy Requirement

To use the reserved domain, you need Caddy deployed: 
uc dns reserve
# If Caddy is not deployed:
Deploy the Caddy reverse proxy service ('uc caddy deploy') to enable internet
access to your services via the reserved or your custom domain.
Deploy Caddy: 
uc caddy deploy

​
Already Reserved

If you try to reserve when you already have a domain: 
Error: domain already reserved
Check your current domain: 
uc dns show

​
Free Service

Uncloud DNS is a free service that provides:
  • Automatic subdomain allocation
  • Automatic DNS record management
  • SSL certificates via Let’s Encrypt (handled by Caddy)

Build docs developers (and LLMs) love

Get started for freeTalk to us