Network and deployment
Mirrored from
iblai/ontologyΒ·docs/network.md. This page is generated β edit it in the repository, not here.
The console has two halves: its pages, and its server half (the route handlers under
/api/host/*, the MCP gateway, the Toolbox processes and the files under $ONTOLOGY_HOME). One
codebase runs them three ways:
| Shape | Setting | Behaviour |
|---|---|---|
| The client's server | ONTOLOGY_PLATFORM, with the engine in AO_URL | the whole console, built from source on the server, beside NVIDIA's engine and Caddy in Docker (install.md); serves that one platform |
| A console hosted elsewhere | NEXT_PUBLIC_ONTOLOGY_RELAY=1 at build | serves pages only; every /api/host/* call is forwarded to the platform's server the browser names in the x-ontology-server header |
| One host run by hand | none, or AO_URL with ONTOLOGY_PLATFORM | pages and server half as one process: a developer's machine (pnpm dev), or one host inside the institution's network behind a TLS proxy |
By default a platform's server serves the whole console at https://<host>/. The console is built
there from source and run by systemd, and NVIDIA's engine and Caddy run in Docker
(install.md). It needs outbound access to the ibl.ai backend, the data
sources it dissects and serves, and OPENAI_API_BASE_URL when a model key is set. Nothing else
but the certificate authority and the host's own hygiene (below).
Topology
admin's browser ββ443βββΆ βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β The platform's server (e.g. ontology.university.edu) β
β 443 β β
βΌ β Caddy :443 (TLS, certificate obtained automatically), :80 β
ibl.ai (sign-in, β /api/host/* β console 127.0.0.1:3000 β
platform data) β /api/auth/* β 404 β
β /internal/* β 404 β
Claude / Codex / β /api/* β NVIDIA's web app 127.0.0.1:3100 β
Cursor ββββββ443βββββββββΆβ (its API, with its own keys) β
β /iblai/api/host/*, β console, prefix stripped β
ibl.ai agents β443βββββββΆβ /iblai/<platform>/<slug>/mcp β
(from ibl.ai egress) β everything else β console: pages, and the gateway β
β at /<platform>/<slug>/mcp β
β β Toolbox 127.0.0.1:<port> β
β β
β console β engine 127.0.0.1:3100, with the server's engine key β
β engine β console /internal/models/v1, with its model key β
β loopback only: console 3000, engine web 3100, engine API 3001, β
β ingestion 3002, Postgres 5434, every Toolbox port β
β volumes: secrets, postgres_data, certificates β
β the console's files: ONTOLOGY_HOME=/var/lib/ontology, β
β platforms/<platform>/{env, apis.yaml, servers/<slug>/β¦} β
ββββββββββββ¬βββββββββββββββββββββ¬βββββββββββββββββββββ¬βββββββββββββββββ
β 443 β db ports β 443, only with
βΌ βΌ βΌ OPENAI_API_KEY
ibl.ai backend data sources OPENAI_API_BASE_URL
ext.ibl.ai SIS Postgres 5432, (default
(129.80.99.227) LMS MySQL 3306, api.openai.com)
Snowflake 443, CRM
Postgres 5432,
HTTP APIs 443
Agents call https://<host>/<platform>/<slug>/mcp. https://<host>/iblai/β¦ is a second address
for the console's host API and gateway, used by a console hosted elsewhere; Caddy strips the prefix.
One platform or any
The engine has no notion of platforms, so each platform has its own, and ONTOLOGY_PLATFORM says
which one a server serves.
- A server with an engine of its own (
AO_URL) serves one platform: the oneONTOLOGY_PLATFORMnames, by its key. Every/api/host/*call and every gateway call for another platform answers403"This server serves another platform." before the server asks ibl.ai anything. The Compose install always brings an engine, so it always needsONTOLOGY_PLATFORM. AO_URLwithoutONTOLOGY_PLATFORM: the server refuses to start, and every host call and gateway call,GET /api/host/healthincluded, answers503"ONTOLOGY_PLATFORM is not set: it names the platform this serverβs engine (AO_URL) belongs to."- Neither set: any platform is served, each through its own
$ONTOLOGY_HOME/platforms/<folder>/engine.json({"url": "...", "key": "..."}), written by the server's operator. That file names an engine on another machine: one on the same machine is refused with a503naming the file, because a local engine has one way in,AO_URLwithONTOLOGY_PLATFORM. A platform with no engine gets503"No engine is connected for ββ. This serverβs operator sets AO_URL, or writes platforms/ /engine.json."
The engine
The server half calls only the engine's web app on 127.0.0.1:3100 (AO_URL). It never calls
ports 3001 or 3002. Its key is AO_API_KEY when one is set. Without one, the first call that needs
the engine signs in to it as the engine's admin (AO_ADMIN_EMAIL, the password in the file
AO_ADMIN_PASSWORD_FILE, with the origin the engine trusts, AO_ORIGIN, default AO_URL's own
origin), makes a key, keeps it in $ONTOLOGY_HOME/engine-key (mode 0600) and uses it from then on.
A key the engine refuses with 401 is dropped, so the next call makes a new one. Nobody has to mint
a key.
Compose runs every service on the host's network (a Linux host), each listening on 127.0.0.1
only, with the engine's web app on 3100 (3000 is the console's). The engine then reaches a database
on this machine at 127.0.0.1, the address the runtime uses for it too. The engine's API trusts
its caller's identity header, which is why 3001 and 3002 stay on loopback. The services are
NVIDIA's own images, pulled from nvcr.io at the release compose.yaml names.
NVIDIA's API is at https://<host>/api/β¦: everything under /api but /api/host (the console's)
and /api/auth, which answers 404 so NVIDIA's sign-in stays off the internet. It takes its own
keys, and its answers carry a sandboxing Content-Security-Policy. NVIDIA's own pages are not
served: on one host name they would share an origin with the console and could read its sign-in.
They open through an SSH tunnel, at http://localhost:3100, as admin@ontology.local:
ssh -L 3100:127.0.0.1:3100 <server>
sudo docker compose exec postgres cat /secrets/admin-password # on the server, in /opt/iblai-ontology
Models
The engine reaches a model only through the console. It calls a loopback route of the console,
POST /internal/models/v1/chat/completions and /embeddings, with a generated key of its own,
checked against the file ONTOLOGY_MODEL_KEY_FILE names (unset, the route answers 404). Caddy
answers 404 for /internal/*. With OPENAI_API_KEY set, the console swaps in the model name
(OPENAI_MODEL, default gpt-4.1; OPENAI_EMBEDDING_MODEL, default text-embedding-3-large),
adds the key, asks for 2048-dimension embeddings and sends the call on to OPENAI_API_BASE_URL
(default https://api.openai.com/v1). The engine never holds the key.
Without OPENAI_API_KEY the route answers 403 and nothing leaves the server: the engine names
terms from names, infers no joins and answers no questions. Connecting a database, the map,
certifying, raw SQL and certified-term tools work either way.
The admin's browser talks to the console and to ibl.ai (ext.ibl.ai) directly for sign-in and
platform data, exactly as os.ibl.ai does. So clients need outbound 443 to ext.ibl.ai as well.
A console hosted elsewhere
A console built with NEXT_PUBLIC_ONTOLOGY_RELAY=1 serves pages only, for platforms whose server
runs elsewhere. ibl.ai hosts one at ontology.iblai.me (staging; ontology.ibl.ai later). It keeps
nothing and holds no secret. Its pages call its own /api/host/* with the admin's ibl.ai sign-in,
the platform as x-ontology-platform and the platform's server as x-ontology-server
(https://<host>/iblai). It forwards each call to https://<host>/iblai/api/host/* with the same
sign-in, only to a public https address, following no redirect, and gives up after 60 seconds.
Without the header it answers 404 "No ontology server is connected for this platform." Its own
/<platform>/<slug>/mcp answers 404: agents call the server.
The browser keeps each platform's server address itself, in
localStorage["ontology_server:<platform>"]; the platform has no record of it. An administrator
connects it by host name under Connect a server, which asks the server's
GET /api/host/health, or with the server control on Config.
One host run by hand
Pages and server half run as one Next.js process on 127.0.0.1:3000: pnpm dev on a developer's
machine, or behind a TLS proxy (Caddy or nginx) on one host inside the institution's network, with
/ and /api/host/* sent to it. Agents call https://<console host>/<platform>/<slug>/mcp. With a
local engine (AO_URL) it needs ONTOLOGY_PLATFORM as well, or it refuses to start; the engine
runs from a checkout of NVIDIA's repository with deploy/auto-ontology.override.yml, on the host's
network as above. On Docker Desktop (macOS, Windows) host networking behaves differently: publish
the ports on loopback there instead. The rest of this document holds, with the console's host in
place of the platform's server.
Firewall rules
Inbound to a client's server
| From | Port | Purpose | Notes |
|---|---|---|---|
| internet | 80 | the certificate's challenge, and the redirect to https | Caddy obtains and renews the certificate itself |
| internet | 443 | the console at / (pages, /api/host/*, /<platform>/<slug>/mcp), the same under /iblai, NVIDIA's API under /api | admins' browsers, ibl.ai's agents on ibl.ai's egress and any console hosted elsewhere: none has an address list you can pin. Every /api/host/* call but GET /api/host/health, and every gateway call, needs an ibl.ai credential; NVIDIA's API takes its own keys. /api/auth/* and /internal/* answer 404. |
| the operator | 22 | SSH, and the tunnel to NVIDIA's own pages | |
| anything else | β | denied |
Inbound to one host on a VPN
| From | Port | Purpose | Notes |
|---|---|---|---|
| VPN CIDR(s) | 443 | console, gateway, playground | the only human entry point |
| ibl.ai agent egress IPs | 443 | /<platform>/<slug>/mcp calls from ibl.ai agents | Ask ibl.ai for the current egress list. The A records below are ingress addresses and may not be the source of outbound agent traffic. Alternative: terminate ibl.ai traffic on the VPN concentrator or a private peering so no public inbound rule is needed. |
| anything else | β | denied |
Ports 3000, 3001, 3002, 3100, 5434 and every Toolbox port are bound to loopback and are never published.
Outbound from the host
| To | Port | Purpose | Required by |
|---|---|---|---|
ext.ibl.ai β 129.80.99.227 | 443 | what a caller's credential is granted, checked on every call | the server half's route handlers and gateway, at ONTOLOGY_DM_URL (else the build's NEXT_PUBLIC_API_BASE_URL) |
| data source hosts | per engine (5432 PostgreSQL, 3306 MySQL, 443 Snowflake and HTTP APIs, ClickHouse's HTTP port) | schema reads, profiling, serving tools, fetching an API's OpenAPI document | auto-ontology, Toolbox, the server half (Fetch Spec) |
OPENAI_API_BASE_URL (default api.openai.com) | 443 | naming terms, resolving joins, embeddings, answering questions | the console's model route, for the engine, and only with OPENAI_API_KEY set. Without it nothing goes out and the engine needs no model endpoint |
| the certificate authority | 443 | obtaining and renewing the server's certificate | Caddy, on a client's server |
| DNS, NTP, internal CA / OS updates | 53, 123, 443 | hygiene | host |
When a client's server is installed or upgraded: GitHub (this repository), mise.run, jdx.dev
and nodejs.org (mise, and the Node it installs), the npm registry (pnpm install brings
Toolbox as @toolbox-sdk/server), Google Fonts (the console's typeface, fetched as it builds),
the container registries (nvcr.io for NVIDIA's engine, docker.io for Caddy and Postgres,
public.ecr.aws only for the console as an image) and Ubuntu's archive
(operations.md). On one host run by hand: the npm
registry. Mirror them internally if the host must stay closed after install, or set
TOOLBOX_BIN to a Toolbox binary you supply.
Roles, policies, API keys and agent connections are written on ibl.ai from the admin's browser, not from the host.
Sign-in: the auth app only returns to origins on the platform's allowed redirect origins on
ibl.ai. Add every origin the console's pages are served from there before go-live:
https://<host> for a client's server, and the origin of any console hosted elsewhere or of one
host run by hand.
Checked on 2026-11-16: ext.ibl.ai does not answer from outside its allow-list (connections from an
unlisted address time out), while the hosted api.iblai.app does. Local development therefore uses
the hosted platform; the deployment sets NEXT_PUBLIC_API_BASE_URL=https://ext.ibl.ai.
Resolved on 2026-11-15: ext.ibl.ai = 129.80.99.227; the hosted cloud (api.iblai.app,
os.ibl.ai, login.iblai.app) = 141.148.72.26. Set NEXT_PUBLIC_API_BASE_URL=https://ext.ibl.ai
so every ibl.ai call from the browser and from the host uses the backend you allow-listed. A
NEXT_PUBLIC_* value is fixed when the console is built, so pages that call ext.ibl.ai come
from a build that had those addresses (operations.md).
The server
half takes its ibl.ai address at run time from ONTOLOGY_DM_URL. Pin by hostname at the proxy and
by IP at the firewall; re-check the IP when ibl.ai announces changes.
What runs where
| Component | Where | Listens | State it keeps |
|---|---|---|---|
| Pages | the client's server (the console's process), a console hosted elsewhere, or one host | the console's origin | none |
| Forwarding | a console hosted elsewhere only | /api/host/*, sent on to the server in x-ontology-server | none |
| Server half | the client's server (a systemd service, or a container on the host's network), or one host | 127.0.0.1:3000 behind the proxy; /api/host/* | the files below; who a caller is kept in memory for 300 seconds, what they are granted for 60 seconds |
| Gateway | same process | /<platform>/<slug>/mcp, also under /iblai on a client's server | servers/<slug>/gateway.log |
| Model route | same process | /internal/models/v1/*, loopback only | none |
| auto-ontology | the client's server, as NVIDIA's own images; or beside one host | web app on 127.0.0.1:3100, its API on 3001, ingestion on 3002, Postgres on 5434 | its Postgres + pgvector volume (postgres_data) |
| Toolbox | host, one process per server | 127.0.0.1, a free port recorded in servers/<slug>/flags.json | servers/<slug>/{tools.yaml, flags.json, revisions/, pid, toolbox.log}, per platform |
| Generated secrets | the client's server | β | the secrets volume, written once: db-password, auth-secret, admin-password, model-key |
| Secrets for serving | host | β | the platform's env, mode 0600: database passwords and API keys |
| TLS proxy | host | 0.0.0.0:443 (and :80 for Caddy) | Caddy's certificate, obtained automatically, in the certificates volume; on one host on a VPN, a certificate from the internal CA |
ONTOLOGY_HOME defaults to .ontology in the console's directory. On a client's server it is
/var/lib/ontology, or /data in the container (the ontology_data volume) when the console
runs as an image. Everything in it is kept per platform:
$ONTOLOGY_HOME/
engine-key mode 0600: the key the server made for its own engine
platforms/<platform>/
engine.json a server without AO_URL: this platform's engine, {"url", "key"}
env mode 0600: database passwords and API keys the runtime reads
apis.yaml, actions.yaml
servers/<slug>/ tools.yaml, flags.json, revisions/, pid, toolbox.log, gateway.log
The folder is the platform's key; a character outside a-z 0-9 - _ is written as ~<hex>~. Two
platforms can each have a server named advising.
Identity on the wire
- Staff in the console: ibl.ai session tokens from
login(see auth.md). The browser sends them to ibl.ai directly and to the console's route handlers, with the platform asx-ontology-platform; the handlers ask ibl.ai what they are granted on that platform. On a client's server the token reaches one place besides ibl.ai: the platform's own server. On a console hosted elsewhere the calls are forwarded with the same token, so it also passes through the hosted console. - ibl.ai agents calling a server: the API key stored in the MCP server registered for that agent on
ibl.ai, sent as
Authorization: Api-Token β¦. It must belong to the platform in the server's address. - People using Claude, Codex or Cursor: an API key issued from the console, as
Api-TokenorBearer. When the server declares an OIDC auth service, the ID token rides along and Toolbox verifies it. - The console holds no ibl.ai secret and issues no tokens, wherever it runs. The server checks each credential by asking ibl.ai with that credential.
- The engine: the server's own engine key, sent only to
127.0.0.1:3100. The engine's model calls carry its generated model key, sent only to the console on loopback.
Hardening checklist
- A client's server has a public DNS name, set as
ONTOLOGY_HOST, and Caddy obtains its certificate. One host on a VPN joins no public DNS; its proxy serves an internal-CA certificate. - The proxy sets
X-Forwarded-Proto: https. The gateway refuses a credential that arrived over plain HTTP from anywhere but loopback. - Each
$ONTOLOGY_HOME/platforms/<platform>/envholds database passwords and API keys, mode 0600, owned by the user the server half runs as. The engine can keep its own connection credentials in Vault if you already run one. Database passwords stay on the platform's server; a console hosted elsewhere holds none. - The four generated secrets are in the
secretsvolume, never incompose.yamlor a.env, and the server's engine key is in$ONTOLOGY_HOME/engine-key.OPENAI_API_KEY, when set, is the one secret the operator supplies: keep the file that holds it closed to other users (mode 600, as the install leaves.env). - NVIDIA's own pages are reachable only through the SSH tunnel, behind their admin password. Its
API under
/apitakes its own keys;/api/auth/*and/internal/*answer404. - Database logins are read-only roles (see guides/connect-data-sources.md). Write tools use a separate login and a separate toolset.
- Allowed origins and hosts are set per server. Toolbox receives both as flags but does not refuse
a foreign
Origin, so the gateway checks both before it checks the credential. - NVIDIA's services are its own published images at one release; pin the images Compose pulls by digest if your policy asks for it. Toolbox is pinned by the lockfile, on one host and on a client's server alike.
- Logs: the proxy's access log,
gateway.logandtoolbox.logper server, the engine's service logs. Ship them to your SIEM from the host.