Applications and Ports

Applications are named TCP ports inside a Workspace that are served over HTTPS by the Cordium portal's reverse proxy. They make development servers, notebooks, dashboards and APIs running inside your Workspaces reachable from your browser, authenticated by your Octelium identity, without any port forwarding or public exposure.

Defining Applications

Applications are defined in the spec.applications field of a Workspace:

spec:
  applications:
    - name: web
      displayName: Storefront
      port: 5173
      isDefault: true
    - name: api
      port: 8080
    - name: storybook
      port: 6006

Field	Description
`name`	A unique name that is used as a subdomain prefix of the Workspace's hostname.
`displayName`	An optional human-friendly name shown in the portal.
`port`	The TCP port that the application listens on inside the Workspace.
`isDefault`	Serves the application at the Workspace's root hostname. At most one application can be the default one.

You can also define them via the --port flag of cordium run and cordium create workspace in the PORT, NAME:PORT or NAME:PORT:default format:

cordium run --image node:24-bookworm \
  --repository https://github.com/acme-corp/storefront \
  --port web:5173:default \
  --port api:8080

note

Applications must listen on all interfaces (i.e. 0.0.0.0) inside the Workspace, not only on localhost, since the portal reaches them through the Workspace's internal tunnel interface. For example, use vite --host 0.0.0.0, jupyter lab --ip=0.0.0.0 or next dev -H 0.0.0.0.

Accessing Applications

Once the Workspace is PREPARING or RUNNING, its applications are reachable at the following URLs:

URL	What it serves
`https://<WORKSPACE>.cordium.<DOMAIN>`	The default application, or the port `8080` if no application is the default one.
`https://<APPLICATION>_<WORKSPACE>.cordium.<DOMAIN>`	A named application (e.g. `https://api_x7k2.cordium.example.com`).
`https://port_<PORT>_<WORKSPACE>.cordium.<DOMAIN>`	Any port, even if it is not declared as an application (e.g. `https://port_9229_x7k2.cordium.example.com`).

Workspaces running in a Region other than default use <WORKSPACE>.<REGION>.cordium.<DOMAIN> instead. You can find a running Workspace's hostname in its status.hostname field, in the portal, and in the CORDIUM_HOSTNAME environment variable inside it.

Applications are authenticated by your Octelium Session: in a browser, you simply log in once via the Cluster's identity providers. Programs and AI agents can access them with an Octelium access token, for example via the Go SDK's authorized HTTP client (read more here). Every request to an application counts as activity for the Workspace's inactivity timeout.

By default, only the Workspace's owner can access its applications. You can share a named application from the portal or via the ShareWorkspacePort API, either with the members of the Workspace's Space (MEMBERS) or with all the Users of the Cluster (ALL). Shared applications are only accessible via their named URL (i.e. https://<APPLICATION>_<WORKSPACE>.cordium.<DOMAIN>), which is perfect for sharing a preview of a branch with your teammates or for a quick design review. Here is an example via the Go SDK:

if err := ws.SharePort(ctx, "web", cordium.ShareWithMembers); err != nil {
	return err
}
fmt.Println("Share this URL with your teammates:", ws.AppURL("web"))

You can stop sharing an application at any time from the portal or via the UnshareWorkspacePort API. The sharing state is part of the Workspace's status (i.e. status.sharedPorts).

note

To expose a Workspace's application beyond Cordium (e.g. to anonymous visitors, to external webhooks, or as a full-fledged Octelium Service with its own Policies and visibility), serve it as an Octelium Service from the Workspace instead (read more here).

Defining Applications

Accessing Applications

Sharing Applications