Public Endpoints

This guide describes the admin page Admin → Public Endpoints and the Public Address Override field of each Topic, GraphRAG Topic and Agent. Together they tell the platform where its containers can be reached from outside.

1. Do you even need it?

Only if other systems call a Topic, GraphRAG Topic or Agent directly. The web UI does not need it. In the web UI, chats, source downloads and pictures always go through this app. They work whether or not a public address is set.

You need a public address when, for example:

  • a script or another application chats with a Topic through its REST API,

  • an external system uses a Topic as a tool,

  • an external client should open the download links in an answer.

Without a public address With a public address

Web UI: chat, downloads, pictures

Works

Works

Source links in answers from a Topic or GraphRAG Topic

Only a path on the container, no complete link

A complete link, for example api.example.com/topics/<id>/…

API clients learn where to call a Topic or Agent

No — they get no address

Yes — the address comes with their login token

The platform does not publish anything itself. Making a container reachable from outside is the job of the cluster or server admin: an Ingress, an API gateway or a reverse proxy, with TLS and rate limits as needed. The platform cannot find out the address you chose. Neither Docker nor Kubernetes knows such an address. So you enter it here, and the platform hands it to each container when it starts.

2. The three kinds of resources

The page has one field per kind. Each field holds a pattern: one address with placeholders, which the platform fills in for each Topic or Agent.

Field Used for What the address is used for

Topics

RAG Topics

Complete download and picture links in answers; the address API clients receive

GraphRAG Topics

GraphRAG Topics

Complete download and picture links in answers; the address API clients receive

Agents

Agents

The address API clients receive. The Agent passes on the links of the Topics it asks, so those links come from the Topics' addresses

Leave a field empty if that kind is not reachable from outside.

3. Placeholders

Placeholder Filled with Example value

{id}

The ID of the Topic or Agent

3f2b8c1e-0000-4000-8000-000000000000

{port}

Its port on the server (RAG Service Port, GraphRAG Service Port or Service Port)

8091

{slug}

Its short technical name: the name in lower case, every other character turned into -, at most 40 characters, then - and the first 8 characters of the ID

support-3f2b8c1e

Which one to use depends on how you publish the containers:

  • Kubernetes, or a gateway with one route per resource: use {id}. The ID never changes. Example: api.example.com/topics/{id}

  • A single Docker host: use {port}. On one host, only the port tells the containers apart. Example: http://kf.example.com:{port} — or https://kf.example.com/p/{port} behind a proxy. On Kubernetes the port does not tell containers apart, so do not use {port} there.

  • Readable addresses: use {slug}, for example {slug}.topics.example.com. Keep in mind that the slug follows the name. If you rename a Topic or Agent, its address changes at its next start, and your proxy must follow.

You may combine placeholders or use none. A pattern without placeholders gives every resource of that kind the same address. On this page that is almost never what you want. In an override for a single resource it is normal (see section 5).

4. Set the patterns

Navigate to Admin → Public Endpoints.

Viewing this page requires the CONFIG_VIEW permission. Changing it requires CONFIG_MANAGE. Without CONFIG_MANAGE the fields are read-only and the Save button is missing.

  1. Under Address Patterns, fill in Topics, GraphRAG Topics and Agents as needed.

  2. Check the line under each field:

    • With a pattern, it shows Example: and the address a sample resource would get (ID 3f2b8c1e-…, port 8091, slug support-3f2b8c1e).

    • With an empty field, it shows either Empty — this kind has no public address. Links work only inside this app. or, when the server setting from section 8 is set, Empty — uses the server setting … with its value.

  3. Click Save. The message reads: "Saved. Each container gets its new address when it is next stopped and started from this app."

Rules for an address

Every field is checked while you type. An invalid field is marked red, and Save refuses with "A pattern is not valid. Fix the highlighted field, then save again."

Rule Message

Only the placeholders {id}, {port} and {slug}

Unknown placeholder {name} — use {id}, {port} or {slug}.

Starts with http:// or https://

Must start with http:// or https://.

Contains a host name

Must contain a host name.

No ?… and no #… at the end — the container adds its own path and parameters

Must not contain a query (?…) or fragment (#…) — the container appends its own.

A well-formed address, for example without spaces

Not a valid URL: … with the reason

A path is allowed, for example api.example.com/topics/{id}. A slash at the end is removed for you, because the container adds its own path.

The section "What the Proxy Has to Do"

The page lists what your proxy, Ingress or gateway must do in front of each container:

  • Forward to port 8080 of the container, without the path prefix. The containers expect their requests at /. If you publish under api.example.com/topics/<id>;, the proxy must remove /topics/<id> before it forwards.

  • Pass the chat streams through without buffering (/chatbot/stream, /graphrag/chat/stream, /agent/stream) and allow long waiting times. Otherwise answers arrive all at once at the end, or break off.

  • Allow requests large enough for your biggest document uploads.

  • Handle the encryption (HTTPS). The containers only speak plain HTTP.

For an NGINX Ingress example, see Making Topics and Agents reachable from outside.

5. One resource with its own address

Sometimes one Topic or Agent is published differently from the pattern, for example under its own host name. Give it a Public Address Override. The override wins over the pattern.

Resource Where to find the field Permission

Topic

Topic detail → Configuration tab → Edit → section Service Configuration, below RAG Service Port

TOPIC_EDIT

GraphRAG Topic

GraphRAG wizard, step 1 Basic Information, section Topic, below the port. Also in edit mode

GRAPHRAG_CREATE or GRAPHRAG_EDIT

Agent

Agent detail → Configuration tab → Edit → section Service Port

AGENT_EDIT

The Topic creation wizard and the New Agent dialog have no such field. Set the override after creation, on the Configuration tab. Through the management API you can also set it at creation (see section 7).

How the field works:

  • Empty means: use the pattern from Admin → Public Endpoints. This is the normal case.

  • The same placeholders and rules as on the admin page apply, and the same messages appear. An override may have at most 500 characters.

  • The line below the field shows the address the container will get at its next start: Public address: …, or "No public address — this container hands out no absolute links, and external clients are not told where to reach it." The line follows the port field while you type, so a {port} pattern shows the new port at once.

An invalid or unusable override does not fall back to the pattern. The resource then has no public address at all. This is on purpose: you set the override because the pattern is wrong for this resource. The form refuses an invalid override, so this happens only when the override names a value the resource does not have, for example {port} without a port.

In view mode, the Configuration tab shows the result as Public Address, or Not configured when there is none.

6. Which address wins, and when it takes effect

Order

For each Topic, GraphRAG Topic and Agent, the platform takes the first address that is set:

  1. its own Public Address Override,

  2. the pattern for its kind on Admin → Public Endpoints,

  3. the server setting for its kind (see section 8),

  4. nothing — the resource has no public address.

An invalid pattern from the page or from the server setting is skipped, and the next step applies. An invalid override is not skipped (see section 5).

When a change takes effect

A container learns its address when it is started from this app. So any change — a pattern, an override, a port used by {port}, or a name used by {slug} — reaches a running container only after you stop and start it in the web UI or through the management API.

  • An automatic restart does not count. If Docker restarts a container on its own, or Kubernetes restarts a pod, the container keeps the address it was started with.

  • When you change the override of a running resource, the panels offer the restart:

    • Topic: the Restart Required dialog with Save Only and Save & Restart.

    • Agent: the Restart Required dialog with Save Only and Save & Restart. If the Agent is not running, you see "Saved. Restart the agent to apply the changes."

    • GraphRAG Topic: after saving a running topic, the Restart Required dialog with Later and Restart Now.

  • A change on Admin → Public Endpoints offers no restart. Restart the affected resources yourself.

  • A restart interrupts running chats for a short time.

7. Where the address shows up

Place Field Content

Login token for API clients — POST /api/auth/token (see Obtain a token)

publicUrl in each entry of topics, graphRagTopics and agents

The address, or null when there is none

Management REST API — reading a resource

publicAddress

The address the container gets at its next start, or null

Management REST API — creating or changing a resource

publicAddressOverride — inside basics for Topics and GraphRAG Topics, at the top level for Agents

The override. null clears it and uses the pattern

Answers of a Topic or GraphRAG Topic

the download link of each source

The address plus the path of the file

The token endpoint and publicAddress show the address as it is configured now. A container that was started before a change still uses its old address until its next start from this app.

Changing publicAddressOverride through the management API on a running resource reports restartRequired. Add ?restart=true to restart it in the same call.

8. Server settings (for administrators)

For a deployment that is set up by files (Helm, GitOps), each kind has a server-side fallback. It applies only when the field on Admin → Public Endpoints is empty.

Kind Property Environment variable

Topics

topic.public-base-url-pattern

TOPIC_PUBLIC_BASE_URL_PATTERN

GraphRAG Topics

graphrag.public-base-url-pattern

GRAPHRAG_PUBLIC_BASE_URL_PATTERN

Agents

agent.public-base-url-pattern

AGENT_PUBLIC_BASE_URL_PATTERN

The same placeholders and rules apply. An invalid value is ignored, and the app log names it. The admin page shows the value under an empty field.

The containers receive the result as the environment variable CYROCK_PUBLIC_BASE_URL. A resource without a public address does not get this variable at all.

9. Troubleshooting

Symptom Likely cause and fix

Download links in answers from an API client are only paths, not complete links

The Topic has no public address, or it was started before the address was set. Set the pattern, then stop and start the Topic in the UI

A new pattern does not reach a container

The container was not stopped and started from this app. An automatic Docker or Kubernetes restart keeps the old address

publicUrl / publicAddress shows the new address, but the links in answers still use the old one

Same cause: both show the configured address, the container still runs with the address it was started with. Restart it from this app

A resource shows Not configured, although it has an override

The override names a value the resource does not have, for example {port} without a port. An unusable override does not fall back to the pattern. Fix or clear the override

All Topics got the same address

The pattern has no placeholder. Add {id}, {port} or {slug}

The address of a Topic or Agent changed after a rename

The pattern uses {slug}, which follows the name. Use {id} for addresses that never change, or update the proxy

The link opens, but the container answers 404

The proxy forwards the path prefix. Remove the prefix in the proxy — the containers expect requests at /

Chat answers through the proxy arrive all at once, or break off

The proxy buffers the stream or its timeout is too short. Switch off buffering for the stream paths and allow long timeouts

Large uploads through the proxy are refused

The proxy’s request size limit is too small. Raise it

The link works only on the machine of the Docker host

The pattern uses localhost or an internal host name. Use a host name that external clients can resolve

An empty field on the page shows Empty — uses the server setting …

The server setting from section 8 applies. Fill in the field to override it, or change the server setting

Fields are read-only, Save is missing

Your role lacks CONFIG_MANAGE

Related