Direct Connection
A direct connection goes straight from a Cardinal app to your Media Server. Cardinal Cloud tells the app where your server is and gives your server the certificate it needs to answer over HTTPS, but the connection itself never passes through Cardinal's infrastructure and nothing about it is metered.
Direct connections are free on every subscription tier, and they are what Remote Access tries first. The relay exists for when a direct connection is not possible.
Your hostname and certificate
Your Media Server is reachable at a hostname derived from its instance ID, a unique identifier created the first time the server starts and stored in its database:
abc123.connect.cardinalapps.host
└──┬─┘
└ your server's instance ID
Fig. 1 — hostname structure
Cardinal issues a TLS certificate for that hostname and delivers it to your Media Server automatically. The certificate renews on its own, and there is nothing to install or configure.
The certificate is what makes a direct connection possible at all. Browsers refuse to send an app's requests to a server that cannot prove its identity, and a server on your own network has no way to obtain a public certificate by itself. Cardinal obtains one on your behalf and hands it over, which is why connections on your own network are encrypted too.
Actions that change your hostname
Two actions replace your instance ID. Each gives your server a new hostname and a new certificate, and any bookmark, saved connection, or app still pointing at the old hostname stops working.
| Action | Why the hostname changes |
|---|---|
| Factory reset | The instance ID is regenerated by design, so the server can be claimed by whoever sets it up next. |
Deleting the server's /config volume, for example docker compose down -v | The instance ID lives in the server's database. Removing the volume destroys it, and the next start generates a new one. |
Actions that do not change your hostname
None of the following affect your hostname or your certificate. The server reconnects at the same address:
- Turning Remote Access off and back on
docker compose restart, or restarting the container by any other meansdocker compose downwithout-v, followed bydocker compose up- Losing power, losing the internet connection, or being offline for an extended period
- Upgrading the Media Server to a new version
Limits on new certificates
Each Cardinal account can obtain a limited number of new certificates per week. There is no limit on certificate renewal.
For example, when you perform a factory reset on a server that was using Remote Access, and then you enable Remote Access again on the fresh installation, you will be assigned a brand new certificate because you have a new Media Server instance ID. If you hit your limit for the week then you will have to wait for a certificate to replenish before you can use a direct connection again.
Relay access is not affected by certificate limits.
How apps choose a route
Your server usually has more than one address that works, and which one is best depends on where the app is. Cardinal apps ask Cardinal Cloud for a list of candidates and dial them in order, taking the first that answers.
Local candidates come first, then public ones:
| Order | Candidate | Used when |
|---|---|---|
| 1 | Local (LAN) — your server's address on your own network | The app is on the same network as the Media Server |
| 2 | Public (WAN) — your network's internet-facing address | The app is somewhere else |
Every candidate is a hostname under your server's own hostname, with the address encoded into the leading label:
192-168-1-40.abc123.connect.cardinalapps.host → 192.168.1.40
Fig. 2 — a local candidate
That is what lets a connection inside your house be encrypted with the same certificate as one from the other side of the world: the name is public and covered by your certificate, while the address it resolves to is private and never leaves your network.
Two details are worth knowing:
- Local candidates require the server to know its own network addresses. A Media Server inside a Docker bridge network — the Quick Start default — cannot discover them, so it advertises none, and apps at home connect over the public route instead. Set
CONNECT_LAN_IPSto tell it, or use the host-networking compose template. - IPv6 often rescues a connection that IPv4 cannot make. Alongside your network's public IPv4 address, the server reports any globally routable addresses it holds on its own interfaces. On a connection behind carrier-grade NAT, where no port forward is possible at all, an IPv6 address is frequently the only direct route there is — and it works without any router configuration.
Candidates are handed out untested, in preference order. An app that cannot reach any of them falls back to the relay.
Getting the connection through your router
Local connections need nothing from your router. A public one does: your Media Server has to be reachable from the internet on the port it publishes, which means your router has to forward that port inward.
Both parts are reported in the Admin Dashboard, under Cloud Services → the Remote Access card → Configure:
| Readout | What it means |
|---|---|
| HTTPS listener | Whether your Media Server is answering HTTPS with its certificate. Running is what you want; Stopped means no direct connection is possible at all. |
| Automatic port forwarding (UPnP) | Whether Cardinal opened the port on your router for you. |
| Public URL | The address apps dial from outside your network. This is the one to copy into a bookmark. |
Automatic port forwarding
The Media Server can ask your router to open the port itself, using UPnP or NAT-PMP. When it works there is nothing to configure. When it does not, the drawer says why:
| Reason | What to do |
|---|---|
| Unavailable on this container network | UPnP needs host networking. Switch to the host-networking compose template, or forward the port by hand. |
| No UPnP gateway found on this network | Your router has UPnP disabled or does not support it. Enable it, or forward the port by hand. |
| No free external port on the router | Something already holds the port. Free it, or forward a different one by hand. |
| Waiting for the HTTPS listener | Nothing to do. The mapping is made once the listener has a certificate and is running. |
Many people prefer to forward the port manually regardless — a mapping you made yourself does not disappear when the router reboots or when UPnP is turned off later.
Forwarding the port by hand
Forward the port your deployment publishes to the same port on the machine running the Media Server. The Quick Start publishes 24900.
Cardinal probes your server from the outside to confirm the forward works, and the Public URL reflects what the probe actually reached. If your server answers on port 443 externally, the URL has no port in it at all, which is the tidiest result and the one most likely to survive a restrictive network on the far end.
A forward that does not work is not a failure state — your server stays connected and apps fall back to the relay. It costs you speed and relay bandwidth, not access.
Custom addresses
Instance IDs make for a hostname nobody can remember. A custom address replaces it with a name you choose:
brianflix.connect.cardinalapps.host
└───┬───┘
└ the name you chose
Fig. 3 — a custom address
You do not need a domain of your own. The name is a label under Cardinal's domain, and the certificate that covers it is issued and renewed by Cardinal in exactly the same way as the one for your instance ID.
Your original instance ID address keeps working after you claim a name — both addresses reach the same server. Nothing that already points at the instance ID address needs to be updated.
Choosing a name
A name must be:
- Between 3 and 30 characters long
- Made up of lowercase letters, digits and hyphens
- Free of a leading or trailing hyphen
The field checks each name as you type it and tells you whether it can be claimed. Some names are already taken, and others are held back — names that would impersonate Cardinal, names that collide with infrastructure, and a blocklist. All of them report the same way, as unavailable, without saying which case applies. If a name you want is refused, pick another one.
Claiming a name
In the Admin Dashboard, go to Cloud Services → the Remote Access card → Configure → the Direct Connection section, and enter the name you want under Custom address.
Claiming a name orders a new certificate that covers it, drawn from the same weekly allowance described in Limits on new certificates. The name starts working once that certificate is issued, which normally takes a minute or two. Until then the name does not resolve, and your instance ID address carries everything as usual.
How many names you can have
Names are counted per Media Server, so each server on your account gets its own allowance:
| Subscription tier | Names per server |
|---|---|
| Free | 1 |
| Starter | 1 |
| Pro | 1 |
| Ultimate | 10 |
Changing and releasing names
Names are released from the same place they are claimed. Releasing one is what frees up an allowance slot, so on a tier with a single name, changing your address means releasing the old name and then claiming the new one.
Replacing a name is rate limited, per server: one replacement every 7 days, and no more than two in any 90 days. Adding a name while you are still under your tier's limit does not count against those windows — only replacements do. Once a window is spent, the next replacement is refused until it clears.
A released name is locked for 90 days. Nobody else can claim it during that window, and only the Cardinal account that released it can take it back. After 90 days it returns to the pool and is available to anyone.
Cardinal can reclaim a name that violates policy.
When a direct connection is not possible
Some networks cannot be reached from outside no matter how they are configured. Traffic falls back to the Relay Connection, which always works but is metered against your subscription.
A public URL that works from cellular data but not from your couch, apps at home that will not connect locally, and a custom address that never comes up are all covered in Troubleshooting.
Was this article helpful?