Skip to main content

Custom Domains NEW

Every public service gets a free https://{service}-{slug}.swisblade.com URL. If you own a domain, you can point it at that service too — without giving up control of your DNS. No nameserver delegation, no API keys to hand over: just one CNAME record in your own DNS provider.

Enabling it​

Add custom_domain to a public app service:

{
  "name": "my-project",
  "services": {
    "api": {
      "type": "app",
      "source": { "repo": "github.com/you/api.git", "ref": "main" },
      "runtime": "node",
      "port": 3000,
      "public": true,
      "custom_domain": "app.yourcompany.com"
    }
  }
}

You can also set this from the dashboard: Project → Settings → Custom Domains, without touching stack.json directly.

Setup flow​

  1. Save the domain (via stack.json or the dashboard). This triggers a one-time deploy of your project to prepare it for the new domain — a few seconds, isolated to your own project.
  2. Create a CNAME in your DNS provider's dashboard: 
    Type:  CNAME
    Name:  app.yourcompany.com  (or your root domain)
    Value: api-{your-slug}.swisblade.com
    Proxy: DNS only (not proxied)
    Find your exact free URL on the project's Public Endpoints card. If your DNS provider proxies traffic by default (e.g. Cloudflare's orange cloud), turn that off for this record — Swisblade needs to see the real connection to issue a certificate and route traffic.
  3. Click "Verify & Activate" in Settings once the CNAME has propagated. Swisblade checks that the domain actually resolves to its servers, then activates routing and requests a dedicated TLS certificate — automatically, no further action needed.

If verification fails, the error tells you what the domain currently resolves to, so you can check your DNS record.

Why no nameserver delegation​

Some platforms ask you to point your domain's nameservers at them, taking over all of its DNS. Swisblade doesn't — you keep managing your own zone (email, other subdomains, everything) and just add one record. This is the same model used by most major hosting platforms.

TLS certificates​

Your free *.swisblade.com URL and your custom domain use separate certificates, both from Let's Encrypt, both renewed automatically. There's nothing to manage.

Using it with Authentication​

If the service also has auth enabled, your custom domain inherits the same login protection as the free URL. One extra step: add your custom domain's callback URL to your OAuth provider's client configuration alongside the existing one, e.g. for Google:

  • Authorized redirect URI: https://app.yourcompany.com/oauth2/callback
  • Authorized JavaScript origin: https://app.yourcompany.com

Most providers let you register multiple redirect URIs on the same OAuth client — you don't need a second one.

Removing a custom domain​

Clear the custom_domain field (or use the dashboard) and redeploy. The free *.swisblade.com URL keeps working regardless — it's never removed.