• Get started

    • Getting started
    • Concepts
    • Tour
  • Using shpyrd

    • Deploying
    • shpyrd.yaml
    • Resources
    • Databases and caches
    • Domains and exposure
    • Sign-in for your app
    • Teams, roles and security
    • AI assistants (MCP)
    • Logs
    • Dashboard
    • CLI reference
  • Running it yourself

    • Installation
    • Oracle Cloud (OKE)
    • AWS (EKS)
    • Extensions and sign-in
    • Platform backups
    • Architecture guide
  • Project

    • Design principles
    • Roadmap
    • How to contribute
    • Support the project
  1. Using shpyrd
  2. Domains and exposure
Sign in
Start free

Domains and exposure

The hostname every project gets, custom domains you own, and which load balancer serves a project.

Every project is served at its own hostname with a trusted certificate: on shpyrd cloud, https://<workspace>-<slug>.shpyrd.app, such as acme-shop.shpyrd.app; on a cluster you run yourself, https://<slug>.<domain>. A workspace can bring a domain of its own for all its apps, projects can also take custom domains one by one, and exposure decides whether the public or the private load balancer serves a project.

The project hostname

acme-shop.shpyrd.app on shpyrd cloud; on a cluster you run, shop.oci.example.com on a cloud profile or shop.shpyrd.test / shop.127.0.0.1.nip.io locally: the slug plus the domain. A new slug (shpyrd projects rename shop "Shop" --slug store) moves the hostname; the old one redirects for 30 days. It stays in DNS as the target of custom domain records. By default it serves the project; when a custom-domain redirect is enabled, it redirects visitors and shpyrd open uses the ready custom domain. On cloud profiles with a DNS provider, one wildcard certificate covers every project hostname, so a new project is trusted from its first request; without one, each project gets its own certificate from Let's Encrypt (cloud) or the platform CA (local).

Custom domains

A project's own domains work the same on shpyrd cloud and on a cluster you run: signed in, with the CLI or on the project's Domains page (developers and admins). To give every app of the workspace a name under one domain of yours, see The workspace's own names.

shpyrd domains add www.myprod.com --project shop
Added www.myprod.com to shop. Create one DNS record at your provider:
  CNAME    www.myprod.com                           -> shop.oci.example.com  or, for a zone apex that cannot hold a CNAME:  A        www.myprod.com                           -> 147.15.59.84
Waiting for www.myprod.com to resolve here and for its certificate ... done.
https://www.myprod.com serves shop.

That is the whole flow, the same as on Heroku or Render: pointing DNS at the platform is the proof that you control the domain. No verification record, no button to click. Once the name resolves to the front door, cert-manager proves control to Let's Encrypt over HTTP and issues the certificate; the command waits (Ctrl-C keeps the domain; the certificate still comes) and the project's Domains page shows the state of each host, refreshing on its own.

HostRecord to create
a subdomain (www.myprod.com, app.acme.io)CNAME to the project hostname
a zone apex (myprod.com)A to the front door's address where it has one (the reserved address on Oracle Cloud), or ALIAS/ANAME to the project hostname where the provider offers it (DNSimple, Cloudflare, Route 53 alias records). On AWS the front door is a load balancer hostname, so an apex needs the ALIAS form

Each custom domain has its own certificate, so a domain whose DNS is not ready yet never affects the project hostname or the other domains. The page and shpyrd domains list report, per host:

DOMAIN            DNS      CERTIFICATE  NOTEwww.myprod.com    ok       ready        servingmyprod.com        missing  issuing      create: CNAME myprod.com -> shop.oci.example.com (or A -> 147.15.59.84)

dns is ok (resolves to this cluster's front door), missing (no record yet), wrong (points elsewhere; the note says what to change) or unknown (the lookup failed); certificate is issuing, ready, failed (with the certificate authority's reason) or wildcard for a host the platform's wildcard already covers.

Rules: a hostname is served by one project only - adding one another project has names that project; wildcards (*.myprod.com) are not accepted, since Let's Encrypt issues those only through DNS in your zone; the platform's own hostnames are refused. shpyrd domains rm www.myprod.com stops serving a domain and removes its certificate. domains: in shpyrd.yaml declares the same list for a repository.

Let's Encrypt allows 50 certificates per registered domain per week and five failed validations per hostname per hour; cert-manager retries on its own, so a domain whose record arrives an hour late still comes up.

Redirect the platform address

Once a project domain shows DNS ok and a ready certificate, select it under Project › Domains › Redirect the platform address, or run:

shpyrd domains redirect www.myprod.com --project shopshpyrd domains list --project shopshpyrd projects info shop

The platform hostname sends an HTTPS 308 redirect to the chosen domain, preserving the path and query string (and the HTTP method and body). For example, acme-shop.shpyrd.app/orders?sort=new redirects to www.myprod.com/orders?sort=new. Other custom domains continue serving the app. DNS and TLS at the platform hostname remain in place, so existing CNAME records keep working. Certificate issuance and renewal remain on the custom domain.

This changes routing without redeploying the app. Private apps still require sign-in at the destination; platform sign-in and callback routes remain available. Sleeping apps wake through the destination as usual. Project links and previews use the active custom domain.

If DNS or the certificate stops being ready, the controller resumes serving the platform hostname and retries readiness. Removing the selected domain clears the project setting. To clear it explicitly:

shpyrd domains redirect off --project shop

With no project redirect, the workspace default applies. Otherwise both addresses serve the app. A 308 can be cached by browsers, so a browser that cached an earlier redirect may keep using it after the setting is changed.

The workspace's own names

On shpyrd cloud a workspace answers at an address under the workspaces domain — demo.shpyrd.cloud — and its apps under the apps domain, the workspace's name first — demo-<app>.shpyrd.app. A workspace can bring names of its own (Workspace › Domains, owners):

  • Address. Owners change the label: demo.shpyrd.cloud becomes acme.shpyrd.cloud and every app moves with it (demo-shop.shpyrd.app becomes acme-shop.shpyrd.app). The label is lowercase letters and digits, no dashes, and cannot be another workspace's name, address or domain, or a reserved word (login, api, …). The old address — dashboard and app hosts alike — redirects permanently for thirty days, and nobody can take it meanwhile. People signed in sign in again at the new address. shpyrd workspace address acme.
  • Custom domains. A name the company owns, intranet.acme.com, in CNAME mode: two CNAME records (intranet.acme.com and *.intranet.acme.com, both to the workspace address) and one TXT record to prove the domain — the page and shpyrd workspace domains add intranet.acme.com print them. After verify, the platform issues a certificate for the domain and one per app host, and the dashboard and every app answer there too (expenses.intranet.acme.com). Make it primary (owners) and the dashboard, the app links and the identity tokens' issuer use it; the address keeps answering. Its dashboard pages then live at the domain, but the address still serves the workspace's sign-in, for the internal apps people enter from the workspace: they are entered through the address, and people sign in there on the way. Delegated (NS) mode, where the platform runs the zone and issues a wildcard, comes later.

On a verified primary domain, Redirect app addresses makes the platform address of every app redirect to its name under that domain. Each app waits for its own DNS and certificate before redirecting. A project's selected redirect domain takes precedence. The workspace dashboard and sign-in addresses keep their existing behavior.

shpyrd workspace domains redirect intranet.acme.comshpyrd workspace domains serve intranet.acme.com  # stop workspace app redirects

Removing or demoting the primary domain suspends workspace redirects. The saved preference applies again when a verified primary domain exists.

Exposure: external or internal

Self-hosted: cloud profiles can run two front doors: the external load balancer with a public address, and an internal one, reachable only from inside the network (VPN, peered VCN, bastion). Every project and the platform itself are external by default; a project moves with one setting:

shpyrd exposure internal --project backofficeshpyrd exposure external --project backoffice

or the badge in the project's header ("public internet" or "local network"; developers and admins click it), or exposure: internal in shpyrd.yaml. On shpyrd cloud, internal exposure is available only when the platform operator has enabled private networking for the workspace; operator-owned workspaces have it by default. Self-hosted OSS/EE keep internal exposure available. Enabling the setting does not create a VPN or VPC connection. Changing it re-renders the project's Ingress on the other controller - no release, no downtime for the instances - and the DNS record for its hostname follows on the provider's next sync, pointing at the internal address. Certificates keep working: the wildcard covers the hostname, and a custom domain's certificate is issued through the front door the domain points at.

The internal controller exists when the cluster was installed with --internal-lb-subnet <subnet ocid> (Oracle Cloud: the private load balancer subnet that contrib/oci/terraform creates). Without it, setting a project internal is refused with an explanation. The dashboard and sign-in page can move behind the internal front door too, once a team has the network to reach them: shpyrd cluster init --platform-exposure internal.

The console's Overview shows both front doors with their addresses, and the launcher marks internal apps.

Local profile

Self-hosted: the local profile has one front door (kind's host ports or your Caddy) and no private network, so exposure is accepted but both values map to the same controller. Custom domains work the same way as on cloud profiles: point a name at the machine and the platform CA issues the certificate (shpyrd cluster trust-ca once).

On this page

  • The project hostname
  • Custom domains
  • Redirect the platform address
  • The workspace's own names
  • Exposure: external or internal
  • Local profile
Back to top
  • AI Community
  • Vibe Coders
  • Developers
  • Businesses
  • FDEs & Implementation Partners
  • Getting Started
  • Pricing
  • Docs
  • Changelog

© 2026. shpyrd. All rights reserved.LegalTerms of ServicePrivacy Policy