Skip to content
Brig docs

Custom domains

Every workload can get a free managed URL on *.brig.run (see Networking). To serve it under your own hostname — api.example.com — register a custom domain. Brig verifies you own the domain, then the edge obtains and renews a certificate for it automatically.

Add a domain

Section titled “Add a domain”
Terminal window
brig domain add api.example.com api

That binds the hostname api.example.com to the workload api (in the production env by default; pass --env for others). The command prints the two DNS records you need to create:

registered api.example.com [production] for workload api (id=42, status=pending)


To activate api.example.com, add these DNS records at your registrar:


  1) Point the hostname at your Brig fleet:
       Type  A
       Name  api.example.com
       Value 203.0.113.42


  2) Prove you own example.com (one-time):
       Type  TXT
       Name  _brig-verify.example.com
       Value brig-verify=a1b2c3d4e5f6g7h8i9j0


Once DNS propagates, run `brig domain verify api.example.com` to promote the domain.
  • The A record points the hostname at your fleet so traffic reaches the edge.
  • The TXT record proves you control the registrable domain (example.com). It’s checked once; you can remove it after the domain goes live, though leaving it costs nothing.

Flags:

FlagDefaultMeaning
--envproductionEnvironment whose workload to bind.
--challengehttp-01ACME challenge type: http-01, dns-01, or byo (bring your own cert; skip automated issuance).

Verify

Section titled “Verify”

Once DNS has propagated, promote the domain:

Terminal window
brig domain verify api.example.com

Brig looks up _brig-verify.example.com, checks the token matches, and on success records ownership and moves the domain toward live:

✓ api.example.com verified (status=live)

If the TXT record isn’t visible yet you’ll get a verify_fail with the exact record it expected — fix DNS and re-run. Verification is safe to retry.

Status lifecycle

Section titled “Status lifecycle”
StatusMeaning
pendingRegistered; TXT ownership not yet proven.
verify_failTXT lookup failed or the value didn’t match. Re-run verify.
verifiedOwnership proven; certificate issuance queued.
acquiring_certACME issuance in flight at the edge.
liveCertificate installed; the hostname serves your workload.
cert_failIssuance failed after verification (usually the A record isn’t pointing at the fleet yet).

List, inspect, remove

Section titled “List, inspect, remove”
Terminal window
brig domain list                    # all domains (add --env to filter)
brig domain show api.example.com    # workload, status, challenge, verified_at, last error
brig domain remove api.example.com  # --force to skip the confirm prompt

Removing a domain deletes its routing and sweeps the issued certificate if no other domain still references that hostname.

How TLS works

Section titled “How TLS works”
  • Managed *.brig.run URLs are covered by a central wildcard certificate issued via DNS-01 and renewed automatically — nothing to configure.
  • Custom domains are issued per-host. Once your A record points at the fleet, the edge completes an HTTP-01 ACME challenge for the hostname, installs the cert, and renews it before expiry. Private keys are sealed under your tenant key at rest.