Domínio curinga (*.seudominio)
Escopo do token: domains:write (e projects:read para ler). O serviço precisa ser public.
Um domínio curinga (*.azarod.com) liga todos os subdomínios de um nível de um domínio seu a um único serviço. O serviço recebe o Host original e decide o que mostrar. Conta 1 domínio na cota, não importa quantos subdomínios existam.
Quando usar
Seção intitulada “Quando usar”- Multi-tenant ou multi-estúdio: cada cliente ganha
cliente.seusite.comsem você cadastrar um domínio por cliente. O app lê oHoste escolhe o conteúdo. - Ambientes efêmeros por branch, preview ou usuário, quando o app mesmo cria os nomes.
- Não use se você tem poucos subdomínios fixos: domínios exatos são mais simples, e cada um pode apontar para um serviço diferente.
Passo a passo
Seção intitulada “Passo a passo”-
Cadastre o curinga no serviço, com
hostnameno formato*.dominio(um único*, no início, seguido de ponto e de um domínio completo). -
Crie no seu DNS o que a resposta mandar:
Registro Nome Valor CNAME*.azarod.como alvo da resposta ( dns.value,cname.<domínio de apps>)TXT_nebular-verify.azarod.comnebular-verify=<token>(deverification.value)- O
TXTfica no apex do curinga (azarod.com), sem asterisco. O nome antigo_nebular-challenge.azarod.comtambém vale. - Se o seu provedor de DNS não aceita CNAME curinga, use
A(eAAAA, se vierem) em*.azarod.comcom os IPs dedns.alt. - Com Cloudflare, deixe os registros em DNS only (nuvem cinza); o proxy laranja é recusado (
proxied).
- O
-
Verifique: espere o worker ou chame
POST .../domains/{d}/verifyatéstatusseractive.
A verificação testa um nome aleatório sob o apex (algo como a1b2c3d4e5f6.azarod.com) e exige que ele resolva para a plataforma. Por isso criar só o registro sharkking.azarod.com não ativa o curinga: o registro precisa ser o curinga (*).
SUF=$(date +%s)-$RANDOMP=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \ -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \ -H "Idempotency-Key: curinga-proj-$SUF" \ -d "{\"name\": \"demo-curinga-$SUF\"}" | jq -r '.id')S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" \ -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \ -d "{\"visibility\": \"public\", \"slug\": \"demo-curinga-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}" | jq -r '.id')
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/domains" \ -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \ -H "Idempotency-Key: curinga-add-$SUF" \ -d "{\"hostname\": \"*.curinga-$SUF.exemplo.test\"}"{"id": "01jb7k6a5q8r7t2v4w6x8y0a4f", "hostname": "*.azarod.com", "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c", "status": "pending_dns", "wildcard": true, "covers_example": "exemplo.azarod.com", "dns": {"type": "CNAME", "name": "*.azarod.com", "value": "cname.nebularapp.xyz"}, "verification": {"type": "TXT", "name": "_nebular-verify.azarod.com", "value": "nebular-verify=7f3a9c"}, "primary": false, "redirect_code": 308, "created_at": "2026-10-19T14:03:11Z"}Os campos novos são wildcard (sempre true aqui) e covers_example (um exemplo de host coberto). O restante é igual ao de um domínio próprio, incluindo os estados.
Pelo MCP
Seção intitulada “Pelo MCP”Com o MCP da Nebular, as tools add_domain e list_domains já aceitam o curinga:
{"name": "add_domain", "arguments": {"project": "01jb7k3a5q8r7t2v4w6x8y0a1b", "service": "01jb7k4a5q8r7t2v4w6x8y0a2c", "hostname": "*.azarod.com", "idempotency_key": "azarod-curinga-1"}}Entregue à pessoa os registros dns e verification do resultado (o agent não cria DNS) e depois chame list_domains até o status ser active.
Verificar agora
Seção intitulada “Verificar agora”POST /v1/projects/{p}/services/{s}/domains/{d}/verify (escopo domains:write, sem corpo) roda a checagem na hora e devolve o domínio com o diagnostic atualizado (reason, message, txt_found, shadowed). Com reason = no_records, falta o CNAME curinga; com txt_missing, falta o TXT no apex.
O que é coberto (precedência)
Seção intitulada “O que é coberto (precedência)”Para cada requisição a plataforma decide nesta ordem:
- Domínios da plataforma (
<slug>.nebularapp.xyz, painel, auth) nunca entram na tabela de domínios. - Domínio exato ativo vence sempre. Se
loja.azarod.comestá cadastrado (em qualquer serviço ou time) e ativo, ele serveloja.azarod.com, não o curinga. Remover o exato devolve o host ao curinga. - Curinga ativo:
*.azarod.comcobre um nível:sharkking.azarod.com. - Fora do curinga:
- o apex
azarod.comnão é coberto; se quiser servi-lo, cadastreazarod.comà parte (conta mais um na cota); - netos não são cobertos:
a.sharkking.azarod.comprecisa de*.sharkking.azarod.com, outro curinga.
- o apex
Só domínio com status = active roteia e recebe certificado. Um curinga pending_dns, error (DNS caído) ou sem serviço não serve nada. O curinga serve direto: não redireciona, não envia Link: canonical e ignora a política de domínios do serviço. O HSTS configurado vale para todos os hosts cobertos.
O curinga nunca é o domínio primário e não redireciona nem pode ser alvo de redirect_to. Variáveis como PUBLIC_URL e NEBULAR_PRIMARY_DOMAIN continuam usando um domínio exato.
Domínios exatos sob o curinga
Seção intitulada “Domínios exatos sob o curinga”Na resposta, diagnostic.shadowed lista os domínios exatos ativos do seu time que estão sob o curinga (eles vencem), e shadowed_others conta os de outros times (o nome de outro time nunca aparece). Serve para você entender por que um host específico não cai no curinga.
HTTPS por host, sob demanda
Seção intitulada “HTTPS por host, sob demanda”Não existe certificado curinga. Cada host sob o curinga recebe o seu próprio certificado no primeiro acesso HTTPS, e a verificação não pede nenhuma chave nem token do seu DNS.
- Teto por apex por hora. Para impedir que um curinga esgote a cota de emissão, a plataforma aprova no máximo 20 certificados novos por hora por apex (padrão; a instalação pode alterar com
API_WILDCARD_ISSUE_PER_HOUR). Acima disso a emissão é recusada com 429 eRetry-After: 3600; o navegador (ou a requisição seguinte) tenta de novo e passa quando a janela libera. Hosts que já têm certificado não consomem o teto, nem os domínios exatos. - Limite do Let’s Encrypt. A autoridade pública limita 50 certificados por semana por domínio registrado. Um rollout de centenas de subdomínios novos pode levar dias para ter todos os certificados.
- Recomendação: antes de um lançamento, pré-aqueça os subdomínios principais, acessando cada um por HTTPS (
curl -sI https://sharkking.azarod.com) com antecedência, espalhado ao longo das horas. O primeiro acesso de um visitante a um host sem certificado pode demorar alguns segundos ou falhar por um instante (e funcionar na tentativa seguinte).
Detalhes gerais em TLS.
Cota e plano
Seção intitulada “Cota e plano”O curinga conta 1 em domains e em domains_per_service (Limites e cotas). A feature features.wildcard_domains do plano (GET /v1/limits e a conta) liga ou desliga o curinga; desligada, só o curinga é barrado e os domínios exatos continuam valendo. features.custom_domains desligada barra todos os domínios.
| Resposta | error |
Quando | Como resolver |
|---|---|---|---|
400 |
invalid_request |
nome fora do formato (*, **.x.com, a.*.x.com, *x.com), sufixo público (*.com.br, *.github.io, *.vercel.app) ou nome que cobriria a própria plataforma |
Use *.seudominio.com, um domínio que seja seu, com um único * no início. |
409 |
domain_taken |
já existe um curinga igual ativo (ou desconfigurado) na plataforma, ou o seu time já tem o nome | Publique o TXT de posse no apex para provar que é seu (veja Problemas comuns), ou remova o duplicado. |
422 |
wildcard_not_allowed |
curinga com redirect_to, PATCH com primary: true, redirect_to num curinga, ou outro domínio redirecionando para um curinga |
Curinga serve direto; use um domínio exato para primário e redirecionamentos. |
422 |
feature_not_allowed (feature) |
o plano não tem features.wildcard_domains (ou features.custom_domains) |
Peça a mudança de plano; domínios exatos seguem funcionando. |
422 |
quota_exceeded (limit) |
cota de domínios do time ou do serviço | Remova um domínio ou peça aumento (Limites e cotas). |
422 |
rate_limited |
mais de 30 domínios criados na última hora pelo time | Espere Retry-After. |
429 |
(resposta do HTTPS do host, não da API) | teto de emissões de certificado do apex | Espere; o navegador tenta de novo. Veja acima. |
404 |
not_found |
domínio de outro time ou serviço | Confira os identificadores. |
Um nome fora do formato volta 400:
SUF=$(date +%s)-$RANDOMH="Authorization: Bearer $NEBULAR_TOKEN"P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" -H "$H" -H "Content-Type: application/json" \ -d "{\"name\": \"demo-curinga-$SUF\"}" | jq -r .id)S=$(curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" -H "$H" -H "Content-Type: application/json" \ -d "{\"visibility\": \"public\", \"slug\": \"demo-curinga-$SUF\", \"source\": {\"type\": \"image\", \"ref\": \"ghcr.io/org/app:1.2\"}}" | jq -r .id)
curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services/$S/domains" -H "$H" -H "Content-Type: application/json" \ -d "{\"hostname\": \"a.*.exemplo.test\"}"{"error": "invalid_request", "message": "Use o curinga no formato *.seudominio.com: um único * no início, seguido de ponto e de um domínio completo."}O curinga que não ativa é diagnosticado como qualquer domínio: veja diagnostic.message (cita o registro curinga certo) e Problemas comuns.
Exemplo: plataforma multi-estúdio com Next.js
Seção intitulada “Exemplo: plataforma multi-estúdio com Next.js”Cenário: *.azarod.com aponta para um serviço Next.js; sharkking.azarod.com mostra o estúdio “sharkking”. O apex e o www ficam no site principal.
- Cadastre
*.azarod.comno serviço da plataforma de estúdios (esta página). - Cadastre
azarod.comewww.azarod.comno serviço do site principal (domínios exatos; vencem o curinga nowww). - Cadastre como domínios exatos, em outros serviços, os nomes reservados que não são estúdios (
api.azarod.com,auth.azarod.com,admin.azarod.com), ou trate-os no app, como abaixo.
Roteamento por Host no middleware.ts:
import { NextRequest, NextResponse } from 'next/server';
const APEX = 'azarod.com';const RESERVADOS = new Set(['www', 'api', 'auth', 'admin', 'app', 'mail']);
// middleware roteia a requisição pelo Host: apex e www vão para o site principal, nomes reservados// e hosts desconhecidos retornam 404 do próprio app, e o resto reescreve para a árvore do estúdio.export function middleware(req: NextRequest) { // A Nebular repassa o Host original e define x-forwarded-host com o host da requisição. const host = (req.headers.get('x-forwarded-host') ?? req.headers.get('host') ?? '') .toLowerCase().split(':')[0];
if (host === APEX || host === `www.${APEX}`) return NextResponse.next(); // site principal if (!host.endsWith(`.${APEX}`)) return new NextResponse('Não encontrado', { status: 404 });
const estudio = host.slice(0, -(APEX.length + 1)); // só um nível: o curinga não cobre netos if (!estudio || estudio.includes('.') || RESERVADOS.has(estudio) || !/^[a-z0-9-]{1,40}$/.test(estudio)) { return new NextResponse('Não encontrado', { status: 404 }); }
const url = req.nextUrl.clone(); url.pathname = `/estudios/${estudio}${req.nextUrl.pathname}`; const res = NextResponse.rewrite(url); res.headers.set('x-estudio', estudio); // as páginas validam se o estúdio existe e dão notFound() se não return res;}
export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };Boas práticas do caso multi-estúdio:
- Host desconhecido = 404 do app. A plataforma entrega qualquer subdomínio do curinga ao serviço; quem sabe quais estúdios existem é o app. Faça a página do estúdio chamar
notFound()quando ele não existir. - Reservados: trate
www,api,auth,adminno app (404 ou redirecionamento) ou cadastre-os como domínios exatos em outros serviços (o exato vence). - Cookie de sessão SEM
Domain=. Sem o atributoDomain, o cookie fica preso ao host que o criou (sharkking.azarod.com) e não vaza para os outros estúdios. ComDomain=.azarod.com, qualquer estúdio leria a sessão dos demais. Use tambémSecure,HttpOnlyeSameSite=Lax. NEXT_PUBLIC_*e URLs absolutas: monte a URL a partir doHostda requisição, não da variávelPUBLIC_URL(que vem de um domínio exato).
Para agents
Seção intitulada “Para agents”Resumo para LLM:
- Cadastrar:
POST /v1/projects/{p}/services/{s}/domainscom{"hostname": "*.dominio.com"}; escopodomains:write; o serviço precisa serpublic. Pelo MCP:add_domain, depoislist_domains. - Resposta traz
wildcard: true,covers_example,dns(CNAME em*.dominio; alternativa A/AAAA emdns.alt) everification(TXT_nebular-verify.<apex>, sem asterisco, no apex). Entregue esses registros a uma pessoa: o agent não cria DNS. - Acompanhe com
GETouverifyatéstatus = active; sigadiagnostic.messagese parar. - Cobre um nível; o apex e os netos não são cobertos; domínio exato ativo vence; curinga não é primário e não redireciona.
- HTTPS por host no primeiro acesso; teto de 20 emissões/hora por apex (
429+Retry-After: espere e tente de novo, não é falha); limite do Let’s Encrypt de 50 certificados por semana por domínio registrado; pré-aqueça os hosts principais. - Erros:
400 invalid_request(nome),409 domain_taken,422 wildcard_not_allowed,422 feature_not_allowed,422 quota_exceeded. Não repita sem alterar a requisição. - O app roteia por
Host/X-Forwarded-Host; host desconhecido deve responder 404 pelo próprio app; cookie de sessão semDomain=.
Veja também Domínio próprio, Redirecionamentos, TLS e Referência de domínios.