Index of every page on this site: llms.txt
All skills
nvidia avatar

/nvidia-ontology-setup

@43fa2d3
by NVIDIA Corporationnvidia/auto-ontology14k stars
1,224
Run it yourself

Set up or troubleshoot the Auto Ontology runtime. Use for Helm (the official install), Docker Compose, developer setup, and MCP connection to an existing deployment.

Use this Skill: https://skilld.dev/gh/nvidia/auto-ontology/nvidia-ontology-setup

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈47 tokens for metadata: the name and description. ≈2.7k when used: this file. ≈8.7k more on demand in 5 files.

Description uses 2.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈189 characters, or 2.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

<!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 -->

Auto Ontology setup

Purpose

Bring up the current Auto Ontology implementation, troubleshoot it, or connect an agent to an instance that is already running. Do not invent a second installer: the official installation is the Helm chart in repository-root DEPLOYMENT.md; Docker Compose runs the same stack on one machine. dev_tools/setup_env.sh is a developer tool, not an installer. Typed setup, connection, ingestion, compilation, and readiness artifacts are in runtime-contract.yaml.

Before a first install, confirm an ontology fits the use case: see When to use in nvidia-ontology-query.

On failure, read troubleshooting.md instead of searching the web.

Instructions

Required questions

Ask these if not already clear. Do not guess a default and emit a command.

  1. Target — Helm on Kubernetes (the official install, and the default recommendation), Docker Compose on one machine, a developer workflow (--dev / --ds, only when changing Auto Ontology itself), or "Auto Ontology is already up, I only need MCP"?
  2. NVIDIA NIM key — is DEFAULT_MODELS_API_KEY (Helm: defaultModelsApiKey) available? Chat and ingest need it.
  3. Admin account — the email and password for the bootstrap admin. Self-service sign-up is disabled, so this is the only way to sign in.
  4. Source database — a connection string (CONNECTION_STRINGS / connectionStrings), or will connections be added in the UI?
  5. Helm only — which chart version, and the URL users will browse to (appUrl).
  6. Compose only — is host 5432 free? POSTGRES_PORT only remaps the host side; containers still use 5432 internally.

Never ask the user to paste secrets into the conversation, and never put them in command arguments. Have the user write them into a values file or .env.

Install with Helm (official)

Releases are published to the public NGC nvidia org (chart and images). Follow DEPLOYMENT.md with the version the user named:

The user creates a values file in an editor (not on the command line, so values stay out of shell history and process arguments), readable only by them, and out of git:

# auto-ontology-values.yaml
defaultModelsApiKey: <API-KEY>
postgresPassword: <POSTGRES-PASSWORD>
adminEmail: <ADMIN-EMAIL>
adminPassword: <ADMIN-PASSWORD>
connectionStrings: <CONNECTION-STRINGS>   # optional; or add connections in the UI
helm fetch https://helm.ngc.nvidia.com/nvidia/charts/auto-ontology-<VERSION>.tgz
helm install auto-ontology auto-ontology-<VERSION>.tgz -f auto-ontology-values.yaml
kubectl port-forward svc/frontend 3000:3000
  • adminEmail and adminPassword are required; the install fails without them.
  • appUrl must be the exact origin users browse to. The default (http://localhost:3000) only fits the port-forward above; set it for a NodePort, ingress, or HTTPS origin.
  • authSecret is generated on first install and kept across upgrades; set it only to share one value across environments.
  • If the chart fetch returns 404, that version is not published yet. Ask the user; do not fall back to the internal staging registry.

This skill does not cover Astra GitOps.

Local: Docker Compose

For running the whole stack on one machine. In the repository root, the user copies .env.example to .env and fills in AUTH_SECRET, APP_URL, AUTO_ONTOLOGY_ADMIN_EMAIL, and AUTO_ONTOLOGY_ADMIN_PASSWORD (all required). Then:

docker compose up -d --build

AUTH_SECRET and APP_URL are required. Without them every page fails with a Better Auth "default secret" error. Fill DEFAULT_MODELS_API_KEY and a CONNECTION_STRINGS value (or plan to add connections in the UI). The full variable list is .env.example.

This builds auto-ontology and auto-ontology-frontend, starts Postgres, pgAdmin, and the ingestion service, runs two one-shot migrate jobs, and starts the app:

  • auto-ontology-migrate applies Alembic migrations to the backend's public schema (catalog and semantic tier). The backend waits for it.
  • frontend-migrate syncs the Prisma frontend schema: users, sessions, API keys, and the OAuth tables MCP sign-in uses. The frontend waits for it.

If sign-in or MCP login fails, check both with docker compose ps -a and docker compose logs frontend-migrate. Read the frontend-migrate log even when it exited 0: it has finished without an error before while leaving MCP login broken.

Service URL
UI http://localhost:3000
FastAPI (internal) http://localhost:3001
Ingestion http://localhost:3002
pgAdmin http://localhost:5050
Postgres localhost:$POSTGRES_PORT (from .env, default 5432)

Developer workflows (--dev, --ds)

Only for people changing Auto Ontology itself; these are not installations. dev_tools/setup_env.sh starts part of the stack in Docker and leaves the rest to run from the checkout. Both need the .env above plus:

cd frontend && pnpm install   # Next.js
# from repo root:
uv sync

--dev runs infra only (Postgres, pgAdmin, ingestion); you run Next.js and FastAPI:

./dev_tools/setup_env.sh --dev
cd frontend && pnpm dev
# repo root:
uv run uvicorn auto_ontology.server.__main__:create_app --factory --reload --host 127.0.0.1 --port 3001

The app factory is create_app() in auto_ontology/server/__main__.py. There is no auto_ontology/server/main.py. uv run python -m auto_ontology.server is the same app without reload (what the container runs).

--ds runs the frontend in Docker and FastAPI on the host:

./dev_tools/setup_env.sh --ds
uv run python -m auto_ontology.server

The frontend image bakes PYTHON_API_URL=http://host.docker.internal:3001, so the API must accept connections from the container, not just loopback. python -m auto_ontology.server binds 0.0.0.0:3001 (what setup_env.sh --ds prints); a --host 127.0.0.1 uvicorn is unreachable from the container on Linux. Because FastAPI trusts x-auto-ontology-user-id, keep port 3001 firewalled from other machines. On native Linux Docker you may need --add-host=host.docker.internal:host-gateway.

Limitations

This skill uses the repository's existing Helm chart and Compose file and does not cover Astra GitOps, change semantic definitions, or treat partial Vault configuration as secret storage. Ask before destructive volume deletion.

Auto Ontology is already up — MCP only

Do not reinstall. Point AUTO_ONTOLOGY_API_URL at the web app (Compose UI is :3000, not FastAPI :3001):

AUTO_ONTOLOGY_API_URL=http://localhost:3000 uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcp

Until the package is on PyPI this needs GitHub credentials that can read NVIDIA/auto-ontology. Client config uses the MCP server URL with a /mcp suffix. People sign in through Auto Ontology; do not put a token on the MCP server.

Confirm the deployment is new enough to be an authorization server:

curl -s -o /dev/null -w '%{http_code}\n' "$AUTO_ONTOLOGY_API_URL/.well-known/oauth-authorization-server"

200 is required. Anything else: run the frontend from the checkout (pnpm dev) and point AUTO_ONTOLOGY_API_URL at that port.

Examples

  • Kubernetes: install the published Helm chart from DEPLOYMENT.md with the admin account and appUrl set.
  • One machine: docker compose up -d --build after filling .env.
  • Existing deployment: do not reinstall; configure AUTO_ONTOLOGY_API_URL and verify OAuth discovery before connecting the MCP client.

Connect a source

Connections come from one of two places, and only one is used:

  • UI-managed (Settings → Connections, or the API below). When any exist, CONNECTION_STRINGS is ignored.
  • CONNECTION_STRINGS in .env is a fallback used only when there are no UI-managed connections. GET /api/connections/source reports whether it is set; it cannot carry schema or table filters.

To add a UI-managed connection (permission connection:manage):

  1. POST /api/connections/test validates credentials and returns the schemas for the allowlist. A 422 carries the driver's error; fix it before creating.
  2. POST /api/connections stores the connection. The 201 only means it was saved: ingestion is triggered best-effort and may fail or still be running.
  3. Verify it landed: GET /api/datasources/dbs (catalog:read) lists the database with the expected tables, GET /api/semantic-compilation/status reports progress, and MCP check_readiness reports no blockers.

Scope is set per connection: a schema allowlist, plus table_allow_regex / table_deny_regex applied at catalog extraction (deny wins; unqualified, case-sensitive names). Env connections have neither. The full table-level scope guarantee is still open in #255, so if particular tables must never be catalogued, sampled, or embedded, say that this is not yet enforceable end-to-end rather than implying it is.

Verify

  1. UI loads at http://localhost:3000 (or the deployed APP_URL / Helm appUrl) and shows the left navigation. Missing nav → stale cookie; see troubleshooting.md.
  2. GET /api/semantic-compilation/status on the web origin authenticates (cookie, x-api-key, or SSO bearer) and returns JSON. calculated: false means the glossary is empty — ingest / compile, do not keep retrying chat.
  3. MCP: OAuth discovery returns 200 (above). Then check_readiness once a client is connected.

Stop

helm uninstall auto-ontology  # Helm; also deletes the postgres-data PVC and its data
docker compose down           # Compose; keep volumes
docker compose down -v        # Compose; wipe Postgres / pgAdmin data

Both helm uninstall and docker compose down -v destroy data; ask first.

Troubleshooting

Use troubleshooting.md for stale sessions, model-key failures, embedding mismatches, port conflicts, and partial Vault configuration. Redact secrets before sharing command output as evidence.

See also

  • troubleshooting.md
  • runtime-contract.yaml
  • nvidia-ontology-query — call Auto Ontology once it is running
  • nvidia-ontology-management — edit the semantic layer
  • CLAUDE.md — maintain Auto Ontology itself

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warningtoday3 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    The skill provides installation, troubleshooting, and MCP configuration instructions for NVIDIA's Auto Ontology system using Helm and Docker Compose. Analysis found that all external resources and tools belong to the vendor's verified infrastructure and follow secure practices for secret management and network operations.

  • Socket2d

    No alerts

  • Snyktoday

    Risk: MEDIUM · 1 issue

Signed by skilld at 43fa2d3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
Other metadata
metadata
{
  "version": "0.3.2",
  "author": "NVIDIA <opensource@nvidia.com>",
  "tags": [
    "nvidia-ontology",
    "install",
    "docker",
    "helm",
    "mcp",
    "troubleshooting"
  ]
}

README badge

README badge for nvidia/auto-ontology/nvidia-ontology-setup