Domains

Every workspace can expose services to the internet with HTTPS. You have several options depending on your needs.

Domain options at a glance

Free preview URLs

When you expose a port, you get instant HTTPS URLs under two domains:

https://a1b2c3.preview.oblien.com  →  workspace:3000
https://a1b2c3.oblien.app          →  workspace:3000

Both work identically — the hash is unique per workspace + port. Preview URLs are instant, public, and ephemeral (removed when the port is revoked or workspace stops). See Public Access for the full API.

Custom domains

Connect your own domain to a workspace for a production-ready URL.

How it works

1. Your domain CNAMEs to edge.oblien.com
2. Oblien edge terminates SSL using an auto-provisioned certificate
3. Traffic is routed to your workspace's internal IP and port
4. Your app serves plain HTTP — HTTPS is handled for you

Step 1: Add DNS records

At your DNS provider, add two records:

The TXT record proves you own the domain. Replace ws_a1b2c3d4 with your actual workspace ID.

Step 2: Verify DNS

Check that DNS is configured before connecting:

const check = await ws.domains.checkDNS({ domain: 'app.example.com' });

if (check.verified) {
  console.log('Ready to connect');
} else {
  console.log('Fix these:', check.errors);
  // e.g. ["No CNAME to edge.oblien.com found", "Missing TXT ownership record"]
}

DNS propagation can take a few minutes. The check uses Google DNS-over-HTTPS for fast, reliable resolution.

Step 3: Connect

const result = await ws.domains.connect({
  domain: 'app.example.com',
  port: 3000,
  include_www: true,
});

console.log(result.url);
// "https://app.example.com"
console.log(result.ssl);
// { status: "active", expiresAt: "2026-06-10" }

This will:

1. Re-verify DNS records
2. Provision an SSL certificate via ACME
3. Register the routing rule in etcd
4. Save the domain config on the workspace

Managing the domain

// Get current domain config
const domain = await ws.domains.get();
// { customDomain: "app.example.com", port: 3000, sslExpiry: "2026-06-10" }

// Renew SSL (auto-renews, but you can trigger manually)
await ws.domains.renewSSL();

// Disconnect
await ws.domains.disconnect();

One domain per workspace

Each workspace supports one custom domain. Connecting a new domain replaces the previous one. To serve multiple domains, use separate workspaces.

SSL certificates

• Provisioned automatically via ACME (Let's Encrypt)
• 90-day validity, auto-renewed when < 14 days remain
• Stored securely and pushed to the edge via etcd
• Force renewal anytime with renewSSL()

Domain survives restarts

When a workspace restarts and gets a new internal IP, the domain route is automatically re-synced. The routing config lives in etcd (edge layer) and the workspace record (database), so it persists across restarts.

Enterprise: custom prefix

Enterprise customers can configure a branded wildcard domain prefix, giving each workspace an automatic subdomain under your own domain:

workspace-1.dev.yourcompany.com  →  workspace-1 port 3000
workspace-2.dev.yourcompany.com  →  workspace-2 port 8080
staging.dev.yourcompany.com      →  staging workspace port 443

Setup

1. Add a wildcard DNS record: *.dev.yourcompany.com → CNAME edge.oblien.com
2. Oblien configures the prefix in your namespace settings
3. Each workspace automatically gets a subdomain based on its name or slug

Benefits

• White-label — your developers see your domain, not Oblien
• Automatic — no manual DNS per workspace
• Wildcard SSL — one certificate covers all subdomains
• Custom TXT prefix — ownership verification uses your configured prefix instead of _oblien

Comparison

Error reference

For the full endpoint reference, see the Domains API.