Change the Public Domain

Purpose

Move an existing Console and inference gateway to new HTTPS origins while retaining the same VPS, database, keys, and private service connections. DNS and tunnel changes alone do not update authentication links or OAuth metadata.

Prerequisites

• Access to the domain's DNS and Cloudflare Tunnel configuration, plus SSH access as the service account that can edit the protected environment files and restart the Console and gateway. Application roles do not grant these host permissions.
• An existing healthy deployment and a backup of its environment files and tunnel routes. Preserve file permissions and keep secrets out of logs and Git.
• Access to the callback settings of any enabled GitHub, enterprise identity, and Connector OAuth applications. Use an existing authorized account for verification.

The examples use fictional console.example.test and api.example.test origins. Replace them with the new public hostnames. Ports 3010 and 4010 below are the existing-VPS topology, not the development defaults.

Procedure

1. Add published application routes to the existing Cloudflare tunnel, preserving its old routes during verification. If cloudflared runs on the VPS, use:

   Public hostname	Tunnel service
   console.example.test	http://127.0.0.1:3010
   api.example.test	http://127.0.0.1:4010

   If the connector runs elsewhere, copy the corresponding existing route's service address. Keep private control port 4001, the Agent runtime, and database listeners private. Preserve existing edge access policies. Wait for DNS and a valid HTTPS certificate before changing the application's origin. See Cloudflare's published applications guide.

2. Register the new Console callbacks for enabled integrations before restarting:

   Integration	Callback at the new Console origin
   GitHub sign-in	/api/auth/callback/github
   Connector OAuth	/api/connectors/oauth/callback
   Enterprise sign-in	The provider-specific callback in Enterprise identity

   Update the OAuth application's homepage too. Retain old callbacks temporarily where the provider allows several. Providers accepting only one callback need a coordinated cutover. Let in-progress sign-ins and Connector authorizations finish first, or restart them on the new origin. For dynamically registered Connectors, an old registration may still contain the old callback; if the provider cannot update it, an authorized administrator must Disconnect and reconnect it to register the new callback. Coordinate that interruption.

3. On the VPS, update the protected environment files actually loaded by the Console and gateway. In this guide's fictional topology these are under /home/mission-control/.config/mission-control; inspect the services' EnvironmentFile declarations and remove conflicting later overrides. Both processes need:

   APP_URL=https://console.example.test
   GATEWAY_PUBLIC_URL=https://api.example.test
   

   Set the Console's explicit origin allowlist:

   TRUSTED_ORIGINS=https://console.example.test
   

   During a transition, include the old Console origin only if it still serves the Console. Leave GATEWAY_MANAGEMENT_URL and private heartbeat/runtime addresses unchanged. Keep BETTER_AUTH_SECRET and API_KEY_PEPPER unchanged; the domain change needs no secret rotation or replacement ordinary virtual key. Update MCP_ALLOWED_ORIGINS or AGENT_ALLOWED_ORIGINS only when an actual browser application's origin changes, preserving other authorized origins.

4. Restart the affected services after allowing active work to drain. Working directory: any directory on the VPS, as its service account:

   systemctl --user restart mission-control-gateway.service
   systemctl --user restart mission-control-console.service
   curl --fail --max-time 15 http://127.0.0.1:4001/readyz
   

   Readiness should recover after component heartbeats arrive. No database migration or YAML activation is required for these URL-only changes. Updating NEXT_PUBLIC_DOCS_URL separately requires a new Console build; an existing documentation hostname or OTLP endpoint can remain in service.

5. Update client base URLs and deployment verification targets. Working directory: repository root on the workstation, before the next normal deployment:

   export DEPLOY_CONSOLE_PUBLIC_URL="https://console.example.test"
   export DEPLOY_GATEWAY_PUBLIC_URL="https://api.example.test"
   

   These select the deployment helper's probes; they do not change production environment files. Model SDK base URLs normally end in /v1; MCP URLs end in /mcp. Reconnect OAuth MCP clients to the new resource URL because their authorization is bound to the exact resource. Review SCIM client base URLs when enterprise provisioning is configured.

6. Move documentation and telemetry as described below, then complete verification before retiring old routes. API clients and exporters must be configured explicitly rather than relying on cross-host redirects to forward credentials. When retiring the legacy hostnames, Delete the old published application routes from the tunnel and remove their DNS records from the old zone; these are separate settings. Remove the old documentation custom domain from its hosting project, and verify that its DNS record is removed too. Remove old OAuth callbacks, TRUSTED_ORIGINS, and browser-origin allowlist entries and restart the affected processes. Existing clients using a retired hostname must switch to the new URL; no redirect or compatibility alias is retained.

Move documentation and telemetry

Documentation may use a separate static hosting project instead of the VPS tunnel. Add its new custom domain on that existing project. For a public site, verify an unauthenticated visit and publish only material suitable for public readers. If your own documentation requires authentication, configure and verify its Cloudflare Access policy on the new hostname before serving it. Set the Console's NEXT_PUBLIC_DOCS_URL to the new HTTPS docs origin; rebuild when it is embedded in the bundle and restart the Console. Check the actual Documentation link. Set MkDocs site_url to the new documentation origin so subsequent builds emit canonical links and sitemap entries on that hostname. Publish through the existing hosting project's normal release flow.

For OTLP/HTTP in the existing VPS topology, add the new telemetry tunnel hostname with service https://localhost:4318. Copy the old route's Origin Server Name and Certificate Authority Pool settings; keep No TLS Verify off. These settings validate the private Collector certificate and are independent of the public hostname. The signal-specific URL ends in /v1/traces. Working directory: the external application's deployment directory.

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://telemetry.example.test/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"

Keep the exporter's existing telemetry.ingest credential and restart that external application. Exporters using OTEL_EXPORTER_OTLP_ENDPOINT instead use the origin https://telemetry.example.test; stock exporters append the signal path. Mission Control adapters using MISSION_CONTROL_OTLP_ENDPOINT need the complete /v1/traces URL for HTTP. Internal producers already using a private Collector URL can retain it. This HTTP tunnel route does not add public OTLP/gRPC support. No Collector restart or key rotation is required for a hostname-only tunnel change.

Verify TLS and authentication without creating telemetry records. Working directory: any directory on the workstation.

curl --silent --show-error --max-time 15 --output /dev/null --write-out '%{http_code}\n' \
  --request POST --header 'Content-Type: application/x-protobuf' --data-binary '' \
  https://telemetry.example.test/v1/traces

Expected: 401 without credentials. This verifies the route and authentication boundary, not successful ingestion. To verify ingestion, export a permitted synthetic Trace from an authorized external producer and inspect it in the Console following Operate telemetry.

Expected result

The new Console serves sign-in and generates links on its new origin. Connect shows the new gateway address. Existing data and ordinary virtual keys remain available. Each user needs a new session on the new Console domain because browser cookies do not transfer between unrelated domains.

Verification

Working directory: any directory on the workstation. Use real new origins:

curl --silent --show-error --max-time 15 --output /dev/null --write-out '%{http_code}\n' https://console.example.test/sign-in
curl --silent --show-error --max-time 15 --output /dev/null --write-out '%{http_code}\n' https://api.example.test/v1/models
curl --silent --show-error --max-time 15 --output /dev/null --write-out '%{http_code}\n' https://api.example.test/healthz
curl --silent --show-error --max-time 15 --output /dev/null --write-out '%{http_code}\n' https://api.example.test/runtime/v1/runs

Expected: 200, 401, 404, 404, without disabling TLS checks or following redirects. Private control must never become public on the API hostname. Sign in on the new Console with an existing permitted account, inspect Connect, and make an authenticated model-list request with an existing authorized key. Verify enabled GitHub/enterprise sign-in and Connector OAuth callbacks, and reconnect an OAuth MCP client if used. Save timestamped probe results and browser test artifacts with credentials, cookies, callback codes, and personal data omitted. A 200 sign-in page alone does not verify authentication or the cutover. After retirement, verify the old hostname is absent from tunnel routes, hosting custom domains, DNS records, callback registrations, and active service settings. Cached DNS may resolve temporarily, but the old tunnel hostname must no longer serve the application. Do not restore legacy routes just to satisfy stale clients.

Failure recovery

• DNS, certificate, tunnel 502, or an unexpected response: compare the new route's service address with the working old route and check tunnel health. Do not change application URLs until the new routes reach the right listeners.
• Origin rejection, links using the old hostname, or OAuth callback mismatch: check both processes' effective URL settings, the Console allowlist, and the provider registration. Restart affected services and start a new sign-in.
• MCP authorization failure after changing hostnames: reconnect against the new /mcp resource instead of reusing authorization for the old resource.
• A failed cutover: restore the environment backup and any changed provider callbacks, restart Console and gateway, and repeat the probes on the old origins. Keep old tunnel routes until recovery is verified. No database restore is needed.

Related links

• Configure the services
• Deploy to an existing VPS
• Connector OAuth
• Connect an AI client
• Enterprise identity
• Environment variables