Last updated

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:

ShapeSettingBehaviour
The client's serverONTOLOGY_PLATFORM, with the engine in AO_URLthe 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 elsewhereNEXT_PUBLIC_ONTOLOGY_RELAY=1 at buildserves 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 handnone, or AO_URL with ONTOLOGY_PLATFORMpages 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 one ONTOLOGY_PLATFORM names, by its key. Every /api/host/* call and every gateway call for another platform answers 403 "This server serves another platform." before the server asks ibl.ai anything. The Compose install always brings an engine, so it always needs ONTOLOGY_PLATFORM.
  • AO_URL without ONTOLOGY_PLATFORM: the server refuses to start, and every host call and gateway call, GET /api/host/health included, answers 503 "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 a 503 naming the file, because a local engine has one way in, AO_URL with ONTOLOGY_PLATFORM. A platform with no engine gets 503 "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

FromPortPurposeNotes
internet80the certificate's challenge, and the redirect to httpsCaddy obtains and renews the certificate itself
internet443the console at / (pages, /api/host/*, /<platform>/<slug>/mcp), the same under /iblai, NVIDIA's API under /apiadmins' 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 operator22SSH, and the tunnel to NVIDIA's own pages
anything elseβ€”denied

Inbound to one host on a VPN

FromPortPurposeNotes
VPN CIDR(s)443console, gateway, playgroundthe only human entry point
ibl.ai agent egress IPs443/<platform>/<slug>/mcp calls from ibl.ai agentsAsk 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

ToPortPurposeRequired by
ext.ibl.ai β†’ 129.80.99.227443what a caller's credential is granted, checked on every callthe server half's route handlers and gateway, at ONTOLOGY_DM_URL (else the build's NEXT_PUBLIC_API_BASE_URL)
data source hostsper engine (5432 PostgreSQL, 3306 MySQL, 443 Snowflake and HTTP APIs, ClickHouse's HTTP port)schema reads, profiling, serving tools, fetching an API's OpenAPI documentauto-ontology, Toolbox, the server half (Fetch Spec)
OPENAI_API_BASE_URL (default api.openai.com)443naming terms, resolving joins, embeddings, answering questionsthe 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 authority443obtaining and renewing the server's certificateCaddy, on a client's server
DNS, NTP, internal CA / OS updates53, 123, 443hygienehost

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

ComponentWhereListensState it keeps
Pagesthe client's server (the console's process), a console hosted elsewhere, or one hostthe console's originnone
Forwardinga console hosted elsewhere only/api/host/*, sent on to the server in x-ontology-servernone
Server halfthe client's server (a systemd service, or a container on the host's network), or one host127.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
Gatewaysame process/<platform>/<slug>/mcp, also under /iblai on a client's serverservers/<slug>/gateway.log
Model routesame process/internal/models/v1/*, loopback onlynone
auto-ontologythe client's server, as NVIDIA's own images; or beside one hostweb app on 127.0.0.1:3100, its API on 3001, ingestion on 3002, Postgres on 5434its Postgres + pgvector volume (postgres_data)
Toolboxhost, one process per server127.0.0.1, a free port recorded in servers/<slug>/flags.jsonservers/<slug>/{tools.yaml, flags.json, revisions/, pid, toolbox.log}, per platform
Generated secretsthe client's serverβ€”the secrets volume, written once: db-password, auth-secret, admin-password, model-key
Secrets for servinghostβ€”the platform's env, mode 0600: database passwords and API keys
TLS proxyhost0.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 as x-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-Token or Bearer. 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>/env holds 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 secrets volume, never in compose.yaml or 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 /api takes its own keys; /api/auth/* and /internal/* answer 404.
  • 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.log and toolbox.log per server, the engine's service logs. Ship them to your SIEM from the host.

Copyright Β© ibl.ai | support@iblai.zendesk.com