Give the appliance the names its clients use, serve a certificate they trust, and distribute the root CA before anyone needs it.

Reaching the appliance by IP is fine for a first look. Everything else — the browser extension, Claude Code, an API client, a web gateway — refuses plain HTTP and refuses a certificate it does not trust. You give the appliance names, decide which authority signs its certificate, and make your clients trust that authority.

What do I need?

Licence: Any
Role: admin_user

Prerequisites

The appliance has completed the first-boot setup wizard.
You can create A records in the DNS zone your clients resolve.
You have decided which names the appliance answers on — typically one each for the dashboard, the gateway API and the LLM proxy, or one wildcard covering all three.
You can distribute a root certificate to your client machines, through Group Policy, MDM, or by hand.
For an externally signed certificate: a CA that will sign a certificate-signing request for those names.

The appliance answers on three names, all pointing at the same box: the dashboard your team opens, the API the extension and the firewall block-list call, and the OpenAI- and Anthropic-compatible proxy that Claude Code and API tools point at. Their values live in the appliance's own environment as APP_DOMAIN, API_DOMAIN and PROXY_DOMAIN.

Which variant is yours

Your situation	The path	What it costs you
No internal PKI, private DNS zone	Appliance CA — the default	Distribute one root certificate to the fleet, once
An internal PKI your machines already trust	Your own CA, from a signing request	A signing round trip, and renewals you own
Your PKI issues the key with the certificate	Upload a certificate	The same, plus handling a private key outside the appliance
A publicly resolvable name and a public certificate	Obtain it externally, then upload it	The appliance has no public-certificate mode and requests nothing from a public authority itself
No DNS at all — an IP-only deployment	Appliance CA, with the address in the names field	Every client must trust the appliance CA. No public authority signs for a private address
One certificate covering several hosts	A wildcard from your own PKI, uploaded	The appliance's names field takes hostnames and IPv4 addresses only, so it neither issues nor requests a wildcard
A proxy that re-signs the appliance's own HTTPS to your clients	Nothing on the appliance	Those clients trust the proxy's certificate, not the appliance's, so the appliance's own names matter to the proxy rather than to them
A proxy that re-signs the appliance's outbound HTTPS	Trust its CA for outbound connections	Without it, the model providers and the update channel are unreachable

Give the appliance its names

Create the DNS records

Add A records for the three names to the appliance's IP address, in the zone your client machines resolve.

nslookup app.<your-domain> from a client machine returns the appliance's address. Do this before you issue a certificate: a name that does not resolve cannot be validated by anything.

Tell the appliance which names it answers on

Select Settings → Certificates, enter the names in Names, comma-separated, and select Save names and reissue.

The appliance reissues its certificate with those names in the subject alternative name, on top of its own hostname and IP addresses. The page shows Applying on the host while the change runs and refreshes when it finishes; a second change cannot be queued until then.

Screenshot pendingSettings → Certificates showing the current mode, subject, issuer, expiry and the names field/assets/screenshots/settings-certificates@0.4.png

Choose who signs the certificate

Three paths exist, and the page states which one this appliance is on under Mode.

The default for new installations. The appliance holds a box-local root CA valid for ten years and signs its own certificate from it. You distribute the root once; renaming the appliance or renewing its certificate never repeats that work, because only the certificate changes.

Switch to the appliance CA if the appliance is not already on it

Select Use the appliance CA for HTTPS.

The appliance replaces the current certificate with one from its own CA. Browsers that have not yet trusted that CA warn once more, until you complete the next section.

Warning

An appliance installed from an older ISO can still be on its original bare self-signed certificate, which every browser warns about on every device. The page says so explicitly. Switching to the appliance CA, or installing your own certificate, is what clears it.

Make clients trust the appliance

Download the appliance root certificate

On Settings → Certificates, verify the CA fingerprint (SHA-256) shown on the page, then download cid222-appliance-root.crt.

The download is public, so a machine that does not yet trust the dashboard can still fetch it:

curl -kO https://<appliance-fqdn>/certs/appliance-root.crt

Compare the fingerprint of the file you fetched against the one on the page before you distribute it. Skip this section entirely if you installed a certificate from a CA your machines already trust.

Distribute it to your fleet

Install the root certificate into each platform's machine-wide trust store.

Deploy by Group Policy: Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies → Trusted Root Certification Authorities, then import the file and apply the policy to the workstation OU.

On a test machine, gpupdate /force followed by certmgr.msc shows the certificate under Trusted Root Certification Authorities.

Confirm the trust took on a real client

From a client machine, open the dashboard by name.

The page loads with no certificate warning. A warning here means the certificate did not reach that particular browser's store, not that the appliance is misconfigured — Chrome on Linux and Firefox on every platform read stores that the others do not.

Let the appliance out through a TLS-inspecting proxy

If your network re-signs outbound HTTPS with its own authority, the appliance cannot reach the LLM providers or the update channel until it trusts that authority.

Paste the proxy's issuing CA

On Settings → Certificates, under Outbound trust (TLS-inspecting networks), paste the proxy's issuing CA certificate and select Trust this CA for outbound connections.

The appliance queues the change for the host, which adds the certificate to the trust stores that the gateway and the updater use. This is the outbound direction only and does not change what the appliance presents on 443.

Renewal, and what breaks when it lapses

Settings → Certificates reports Valid until and the days remaining for the certificate it currently serves, and raises a notice on the page when fewer than 30 days remain.

Mode	Who renews it	Lead time you need
Appliance CA	The host, on its next reconcile. Leaves are issued for at most 825 days; the CA that signs them for ten years	None. Distribute the root once and forget it
Your own CA, from a signing request	You. The appliance renews nothing it did not issue	Your CA's turnaround, which is the long pole — start weeks out
An uploaded certificate	You, the same way	The same

An expired certificate does not degrade gracefully. What happens, in the order you notice it:

Browsers refuse the dashboard with an expiry warning, which a person can click through.
The browser extension, Claude Code and any API client refuse the handshake outright. There is no warning to click through, so these fail rather than degrade.
A firewall pulling the appliance's block list stops refreshing it.

Renewing it is the same upload as installing it, and the appliance keeps serving the old certificate until the new one validates — so a renewal attempted and refused costs you nothing.

Warning

A certificate that fails validation is refused and the appliance keeps serving the one it already has, so a bad upload costs you nothing. An expiry you did not plan for does: start an external signing well before the date, because the CA's turnaround, not the appliance, is the long pole.

Verify

From a client machine, open the dashboard by its name over HTTPS. The page loads with no certificate warning.
On Settings → Certificates, Names (SAN) lists every name you entered, and Valid until is in the future with no expiry notice.
The Mode row reads the authority you chose, not the setup-time self-signed certificate.
Point one real client at the appliance — the browser extension, or Claude Code at the proxy name — and confirm it connects rather than failing the TLS handshake.

If it fails

Runbooktls

The certificate has expired, or nothing is serving 443

You might see: ERR_CERT_DATE_INVALID · NET::ERR_CERT_AUTHORITY_INVALID · connection refused on 443 · the dashboard cannot be reached over HTTPS

Before you start

Are you reaching the appliance by the name the certificate was issued for, rather than by IP address?expected · The name you typed appears on the certificate.If not, go to /install/naming-dns-tls first.
Does the appliance respond on the network — does it answer a ping or an HTTP request on another port?expected · At least one of the two connects. If neither does, this is a network or power problem, not a TLS one.If not, go to /install/network-prerequisites first.

Checks

1
Verify something is actually holding port 443 on the appliance host
diagnostics · appliance.tls.servedBy
2
Verify the appliance has a certificate to serve
diagnostics · appliance.tls.mode = "none"
3
Read how many days the served certificate has left
diagnostics · appliance.tls.daysLeft = 0
4
Check whether the certificate is inside the renewal window — 30 days, the `CID_TLS_RENEW_DAYS` default `appliance/tls/ensure-tls.sh` renews an appliance-issued leaf at and warns about a customer certificate at
diagnostics · appliance.tls.daysLeft = 30
5
Verify the appliance root CA is present, so clients can be made to trust an appliance-issued certificate
diagnostics · appliance.tls.caPresent = true

Causes and fixes

Reached when	Cause	Explanation, fix and verification
check 1 fails	`nothing-on-443` (critical)	No process holds 443, so the client's connection is refused before any TLS handshake begins. The browser reports a connection error rather than a certificate error, which is why this does not look like a TLS problem at first. It follows a failed certificate rollout: the front-end refuses to start with an unusable certificate rather than serving a broken one. Fix: Run the host repair from Settings → System Updates, which re-establishes the HTTPS front end and re-applies the appliance's certificate intent. Then reload the dashboard. If repair reports a certificate problem, resolve that first — the front end will keep refusing to start until the certificate it is told to serve is valid. Verify: diagnostics · appliance.tls.servedBy If that does not apply: Attach the support bundle, which carries the host HTTPS inventory.
check 2 fails	`no-certificate` (critical)	The appliance has no certificate configured at all — neither one issued by its own CA nor an uploaded one. Nothing can be served on 443 until it does. Fix: Issue a certificate from the appliance CA under Settings → Certificates, or upload one your organisation's CA signed against a CSR generated there. See Naming, DNS and TLS. Verify: diagnostics · appliance.tls.mode = "none"
check 3 fails	`certificate-expired` (critical)	The served certificate is past its expiry. Browsers refuse the connection outright, and clients that were configured to trust the appliance — the inline proxy's own callers, the browser extension, the endpoint agent — fail closed rather than degrading. Fix: Issue a replacement now. An appliance-CA certificate is reissued in place from Settings → Certificates; an externally signed one needs a fresh CSR, signature and upload. Check the host clock before blaming the certificate: a skewed clock makes a valid certificate look expired. Verify: diagnostics · appliance.tls.daysLeft = 0
check 4 fails	`certificate-expiring-soon` (warning)	The certificate is still valid but inside the renewal window. Renewing now avoids an outage that would otherwise arrive without warning, and gives time for an external CA to turn a CSR around. Fix: Renew the certificate before it expires, following Naming, DNS and TLS. If the certificate is externally signed, start now — the signing turnaround, not the appliance, is the long pole. Verify: diagnostics · appliance.tls.daysLeft = 30
check 5 fails	`ca-missing` (warning)	The appliance root CA is absent, so clients cannot be made to trust an appliance-issued certificate and the public root-CA download has nothing to serve. Every client then reports an untrusted-authority error even when the certificate itself is current. Fix: Re-create the appliance CA under Settings → Certificates, redistribute the root certificate from the appliance's public download path, and reissue the server certificate. Note that reissuing invalidates trust that clients had already established, so plan the redistribution before you reissue. Verify: diagnostics · appliance.tls.caPresent = true

The appliance refuses the certificate you uploaded → The appliance refuses the certificate you uploaded
The certificate is expiring or has expired → The appliance HTTPS certificate is expiring or has expired
Nothing answers on 443 at all → Nothing is listening on 443
A client trusts the root and still warns → that browser reads a store the others do not. Chrome on Linux and Firefox everywhere keep their own; confirm the certificate reached the store that browser actually uses.

Next steps

Update the appliance — an update never changes the certificate the appliance serves.
Hardening checklist — the rest of the settings that are the operator's responsibility rather than the image's.
Backup and restore — the private keys live on the appliance host, so they need to be in your backup.

Naming, DNS and TLS