CoreCube API Connection Topologies

CoreCube exposes two different API surfaces that are often configured from similar-looking URLs:

Caller	CoreCube API surface	Typical base URL	Credential
Third-party chat frontends, such as OpenWebUI	OpenAI-compatible headless API	/v1/chat/completions, /v1/models, /v1/documents/.../file	CoreCube API key, usually cc_*
CoreUI	Native CoreUI product API	/v1/coreui/*	CoreUI setup token in local development, Foundation audience token in production

The main operational distinction is this:

• CoreCube API URL is the URL the calling server or container uses to reach the CoreCube API.
• CoreCube public URL is the browser-facing URL CoreCube uses when it emits signed source-file links.

Those two URLs can be identical in production. They are often different in local development and in multi-Compose deployments.

Port Summary

Port	Product	Role	Required for API connections?
7400	CoreCube	CoreCube server API and production/admin server origin	Yes, this is the CoreCube API port in local Compose
7401	CoreCube	CoreCube Admin Vite dev server and HMR proxy	No for production. Useful only in development for the admin UI/HMR. It can proxy /v1, but API integrations should not depend on it
7500	CoreUI	CoreUI server API and production/server origin	Yes for accessing CoreUI itself
7501	CoreUI	CoreUI Vite dev server and HMR proxy	No for production. Used only for local frontend development

In production, 7401 and 7501 should disappear behind built frontend assets and reverse proxies. They are not part of the product-to-product API contract.

Connection Rules

1. A Docker container cannot use localhost to reach a sibling container. localhost means "this same container".
2. Containers in the same Compose network should use the Compose service name: http://corecube:7400.
3. Containers in different Compose networks need either a shared external Docker network, a host gateway route, or a reverse proxy URL.
4. Different hosts should use HTTPS URLs routed to CoreCube's 7400 server.
5. Browser-facing source-file links must use CORECUBE_PUBLIC_URL or the CoreUI publicBaseUrl setting so users can open signed file URLs.

CoreCube To Third-Party Chat Frontends

Third-party chats use the OpenAI-compatible API. CoreCube remains the knowledge engine; the chat frontend is only the user interface.

1. Same Docker Compose File On The Same Host

Use the Docker service name from the chat container to CoreCube.

OpenWebUI configuration:
OPENAI_API_BASE_URL=http://corecube:7400/v1
OPENAI_API_KEY=cc_...

Recommended CoreCube environment:

CORECUBE_PUBLIC_URL=https://corecube.example.com

For local-only testing, CORECUBE_PUBLIC_URL=http://localhost:7400 is acceptable if the browser runs on the same host and can reach that port.

2. Different Hosts With Different Docker Compose Files

Use the public HTTPS URL of CoreCube. The chat server and browser both need to reach it.

OpenWebUI configuration:
OPENAI_API_BASE_URL=https://corecube.example.com/v1
OPENAI_API_KEY=cc_...

Recommended CoreCube environment:

CORECUBE_PUBLIC_URL=https://corecube.example.com

The reverse proxy should route /v1/*, /api/*, and /admin to CoreCube server port 7400. Do not expose the development HMR port 7401.

CoreCube To CoreUI

CoreUI uses the native CoreCube product API. The browser talks to CoreUI. CoreUI's server talks to CoreCube.

CoreUI has two URL concepts:

CoreUI setting	Meaning
CoreCube API URL, stored as baseUrl	URL the CoreUI server uses for /v1/coreui/*
Browser-facing CoreCube URL, stored as publicBaseUrl	Browser-facing CoreCube origin for signed source-file URLs

3. Same Docker Compose File On The Same Host

Use the CoreCube service name for the server-to-server API URL.

CORECUBE_BASE_URL=http://corecube:7400
CORECUBE_PUBLIC_URL=https://corecube.example.com

In the CoreUI connection page:

CoreCube API URL: http://corecube:7400
Browser-facing CoreCube URL: https://corecube.example.com

If the full stack is behind one production domain, the browser-facing CoreCube URL can be the same CoreCube HTTPS origin used by administrators and browser users.

4. Different Hosts With Different Docker Compose Files

Use the HTTPS CoreCube origin as the API URL and browser-facing CoreCube URL unless there is a private inter-host service network.

CORECUBE_BASE_URL=https://corecube.example.com
CORECUBE_PUBLIC_URL=https://corecube.example.com

In the CoreUI connection page:

CoreCube API URL: https://corecube.example.com
Browser-facing CoreCube URL: https://corecube.example.com

Production CoreUI authentication should use Foundation audience-token exchange. Local static setup tokens are a development/bootstrap convenience, not the target production trust model.

Same Host, Different Compose Files

This is operationally between "same Compose" and "different hosts".

Preferred production patterns:

1. Put CoreUI and CoreCube on a shared external Docker network and use service DNS, such as http://corecube:7400.
2. Route CoreUI to CoreCube through the same HTTPS reverse proxy used by other clients, such as https://corecube.example.com.

Shared external network pattern:

networks:
  opencore_internal:
    external: true

services:
  corecube:
    networks:
      opencore_internal:
        aliases:
          - corecube

  coreui:
    networks:
      - opencore_internal

With that network in both Compose files, CoreUI or OpenWebUI can call:

CoreUI CoreCube API URL: http://corecube:7400
OpenWebUI API URL: http://corecube:7400/v1

Avoid relying on localhost inside either container. If a container must call a port published on the Docker host, use the platform's host-gateway mechanism, for example host.docker.internal in local development.

Development Setup

Local development has extra Vite ports and Docker host-bridge behavior.

Current Local Port Pattern

URL	Meaning
http://localhost:7400	CoreCube API/server from the host browser
http://localhost:7401	CoreCube Admin Vite dev server and HMR proxy
http://localhost:7500	CoreUI API/server from the host browser
http://localhost:7501	CoreUI Vite dev server and HMR proxy

When CoreUI runs in its own Docker Compose file and CoreCube runs in a separate Compose file, CoreUI's container cannot call http://localhost:7400 because that points back to the CoreUI container. The local CoreUI server should call:

CORECUBE_BASE_URL=http://host.docker.internal:7400

CoreUI may still keep the browser-facing CoreCube URL as:

CORECUBE_PUBLIC_URL=http://localhost:7400

http://localhost:7401 is also reachable during local admin development because the CoreCube Vite server proxies /api and /v1 to 7400, but that is a development convenience rather than the default browser-facing API origin:

CORECUBE_PUBLIC_URL=http://localhost:7401

Use localhost:7401 only when deliberately testing the CoreCube Admin Vite/HMR origin or its dev proxy. For normal local CoreCube browser links, prefer localhost:7400.