Skip to content
Edit page
Copy page

Expose AI Workspace

Two addresses leave your network in a production deployment: the workspace URL that people open in a browser, and the control plane address that AI gateways connect to. They serve different audiences, so expose them differently.

Address Audience Typical exposure
Workspace URL, such as https://workspace.example.com/ai-workspace People, through a browser Public, or reachable from your corporate network
Control plane address, such as platform-api.example.com:9243 AI gateways Restricted to the networks your gateways run in

Nothing else needs an address. In the default deployment, the browser doesn't call the Platform API. The backend for frontend (BFF) proxies every call server-to-server, so the Platform API needs no public route for the interface to work. A browser application other than AI Workspace can call the Platform API directly, which needs cross-origin resource sharing (CORS). See Leave CORS off unless you need it.

The path prefix is fixed

AI Workspace serves everything under /ai-workspace:

Path Serves
/ai-workspace/ The single-page application and its client-side routes
/ai-workspace/api/* The BFF's own API, including session, login, logout, and the OIDC callback
/ai-workspace/proxy/* The reverse proxy hop to the Platform API
/healthz The health endpoint, at the origin root
/ A redirect to /ai-workspace/

The application bundle sets the prefix at image build time, so it isn't configurable. That simplifies your routing: one rule routes the whole application with no path rewriting, and several portals can share a hostname without their routes overlapping.

Don't rewrite the path

A rule that strips /ai-workspace before forwarding breaks every asset request, because the bundle references its assets by absolute path. Forward the prefix as-is.

Step 1: Publish the workspace URL

For the configuration on each platform, see Deploy on VMs, Deploy on Kubernetes, and Deploy on OpenShift.

Step 2: Expose the control plane for gateways

A gateway connects to the Platform API directly over HTTPS and WebSocket. It doesn't go through AI Workspace, so it needs its own reachable address.

Match the exposure to where your gateways run:

  • Gateways in the same cluster or on the same host: no external route. Gateways use the in-cluster Service address or the Compose network name.
  • Gateways elsewhere in your network: an internal load balancer, or a private DNS name resolving to the host.
  • Gateways outside your network: a public address restricted by source range, with the registration token as the credential.

For the configuration on each platform, see Deploy on VMs, Deploy on Kubernetes, and Deploy on OpenShift.

Two keys that aren't interchangeable

controlplane_host is display-only. AI Workspace never connects to it. Instead, it substitutes the value into the setup commands it shows an administrator. A wrong value leaves the workspace working and breaks the gateway, which then can't register. The BFF's own hop uses [ai_workspace.control_plane] url instead. See Two keys that aren't interchangeable.

Step 3: Match the redirect URLs to the public hostname

In OIDC mode, both redirect URLs carry the public hostname and the path prefix. They must match what you registered on the identity provider application, character for character.

For the configuration on each platform, see Deploy on VMs, Deploy on Kubernetes, and Deploy on OpenShift.

The callback is a BFF route, not a page in the application. Register /ai-workspace/api/auth/callback on the identity provider. Registering the sign-in page instead makes the code exchange fail. See Connect an identity provider to AI Workspace.

Step 4: Leave CORS off unless you need it

The Platform API's allowed_origins list is empty by default, which disables cross-origin access. Because the BFF proxies browser traffic same-origin, that default is correct for a standard deployment.

Set it only when a browser application other than AI Workspace calls the Platform API directly. List the exact origins.

For the configuration on each platform, see Deploy on VMs, Deploy on Kubernetes, and Deploy on OpenShift.

A wildcard is rejected at startup, so the service can't run with credentialed cross-origin access open to every origin.

Verify

Confirm each address resolves and answers:

# The workspace, from a client network.
curl -sSI https://workspace.example.com/ai-workspace/ | head -1

# The health endpoint, which sits at the origin root.
curl -sS https://workspace.example.com/healthz

# The control plane, from a host on the same network as your gateways.
curl -sSI https://platform-api.example.com:9243/health | head -1

Then open the workspace in a browser and sign in. If the page loads but assets return 404, something in the path is rewriting the prefix.