The filesystem registry that grounds your AI agent sandboxes.

Give every OpenClaw / NemoClaw sandbox a stable, governed view of your data — AWS EFS or classic NFS — from a single config file. Declare each filesystem once, bind it to the sandboxes that may use it, read-only or read-write, by folder path.

Features → How it works → Quick Start → Configuration → Deployment → Resources

Ontology is a digital twin of your organization — a navigable map that AI agents use to understand context and take action. This repository is the storage plane of that idea: the part that grounds agents in real, persistent files.

ibl.ai agents run behind the scenes in self-hosted OpenClaw and NVIDIA NemoClaw sandboxes (see iblai-claw-setup). Those sandboxes are ephemeral; your knowledge bases, student vaults, and working sets are not. Ontology connects the two — mounting the right filesystem, at the right path, with the right permissions, into the right sandbox — driven entirely by one declarative registry.

Think of it as a Vault for the filesystem layer: one source of truth for what storage exists and who may touch it.

• One registry, many filesystems — register any number of AWS EFS and classic NFS filesystems in a single config file.
• AWS EFS, first class — TLS in transit, EFS access points, and IAM-aware mounting via amazon-efs-utils, with automatic fallback to NFS 4.1 when the helper isn't present.
• Classic NFS — point at any server:export, expose a sub-folder, tune mount options.
• Folder-scoped exposure — publish /knowledge out of a filesystem, not the whole export.
• Permission bindings — grant a filesystem to a sandbox read-only or read-write; later rules override earlier ones so a wildcard default can be tightened per sandbox.
• Glob targeting — ["*"], ["*-research"], or explicit sandbox ids decide who gets what.
• POSIX ownership — set uid/gid per mount for correct file ownership inside the sandbox.
• Agent-facing manifest — emit the JSON map an agent reads at startup to know exactly which filesystems it owns and whether each is writable.
• systemd .mount units — render boot-persistent, network-ordered mounts for long-lived sandbox hosts.
• Docker / init-container ready — provision mounts in an init container and share them with the claw process.
• Secrets via env — ${EFS_VAULT_ID} style interpolation keeps IDs and hostnames out of git.
• Dry-run everything — plan shows the exact mount commands before anything changes.
• Zero runtime dependencies — pure-Python core; PyYAML only needed for YAML configs (JSON works without it).

            ibl.ai platform  (chat, mentors, skills)
                       │
                       ▼
         OpenClaw / NemoClaw gateway  (systemd)
                       │ spawns
                       ▼
   ┌──────────────── sandbox ─────────────────┐
   │  agent reads /mnt/manifest.json           │
   │  agent reads /mnt/knowledge   (ro)         │
   │  agent writes /mnt/vault      (rw)         │
   └───────────────────┬───────────────────────┘
                       │ mounts provisioned by
                       ▼
                ┌─────────────┐   ontology.yaml
                │  Ontology   │ ◀── filesystems + permissions
                └──────┬──────┘
            ┌──────────┴──────────┐
            ▼                     ▼
       AWS EFS (TLS)        classic NFS

Three primitives drive everything — filesystems (what storage exists), permissions (who may mount it, where, how), and sandboxes (the consumers). See docs/architecture.md for the full picture.

# 1. Install
git clone https://github.com/iblai/ontology.git
cd ontology
pip install -e ".[yaml]"

# 2. Describe your filesystems
cp config/ontology.example.yaml /etc/ontology/ontology.yaml
export EFS_KNOWLEDGE_ID=fs-0123456789abcdef0      # referenced as ${EFS_KNOWLEDGE_ID}

# 3. Validate the registry
ontology validate

# 4. See what a sandbox would mount — no changes made
ontology plan --sandbox openclaw-prod

# 5. Mount everything that sandbox is permitted (run as root, on the sandbox host)
sudo ontology mount --sandbox openclaw-prod

# 6. Hand the agent its world model
ontology manifest --sandbox openclaw-prod > /mnt/manifest.json

Command reference

Set the config path once with ONTOLOGY_CONFIG=/path/to/ontology.yaml, or pass -c per command. Add -v to print the underlying mount commands.

A registry is one YAML (or JSON) file with three sections. Full reference in docs/configuration.md.

version: "1"

filesystems:
  - id: shared-knowledge          # an AWS EFS filesystem, exposing one folder
    name: "Shared Knowledge Base"
    type: efs
    file_system_id: ${EFS_KNOWLEDGE_ID}
    region: us-east-1
    transit_encryption: true
    root: /knowledge

  - id: scratch                   # a classic NFS server
    name: "Scratch / Working Set"
    type: nfs
    server: nfs.internal.ibl.ai
    export: /exports/scratch

permissions:
  - filesystem: shared-knowledge  # every sandbox, read-only
    mount_path: /mnt/knowledge
    access: ro
    sandboxes: ["*"]

  - filesystem: scratch           # only research sandboxes, read-write
    mount_path: /mnt/scratch
    access: rw
    sandboxes: ["*-research"]

sandboxes:
  - id: openclaw-prod
    runtime: openclaw
  - id: nemoclaw-research
    runtime: nemoclaw

• ${VAR} tokens are expanded from the environment at load time — keep EFS IDs and hostnames out of git.
• Last write wins on a mount_path, so a ["*"] default can be overridden by a sandbox-specific grant later in the file.
• access is ro (default) or rw; set uid/gid to own the mountpoint inside the sandbox.

For long-lived hosts, let systemd own the mounts so they survive reboots and order correctly after the network:

sudo ontology systemd --sandbox openclaw-prod -o /etc/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable --now mnt-knowledge.mount mnt-vault.mount

The examples/docker-compose.yml pattern runs a privileged ontology-mount container that provisions the mounts and shares them with the claw container, then writes the manifest the agent reads:

EFS_KNOWLEDGE_ID=fs-0abc... docker compose -f examples/docker-compose.yml up

Ontology is the storage companion to iblai-claw-setup. Install the claw gateway as that repo describes, then run ontology mount (or enable the systemd units) on the same host before the gateway starts spawning sandboxes.

pip install -e ".[dev]"
pytest -q

Issues and pull requests are welcome. Keep the core dependency-free, add a test for any new backend or resolution rule, and run pytest before opening a PR.

• Product — ibl.ai/ontology
• Claw sandboxes — iblai/iblai-claw-setup
• Agent platform — iblai/os
• Architecture — docs/architecture.md
• Configuration reference — docs/configuration.md

MIT — see LICENSE.