aimodelvault

Universal cross-platform encrypted vault for AI/ML model storage, versioning, conversion, and lifecycle management — agent-first by design, military-grade security, 23+ formats, 29 production features.

A production-ready secure vault, built on FIPS-approved cryptographic algorithms, for storing and managing AI models. Every capability is exposed through three parallel surfaces — CLI, REST/GraphQL, and MCP — with a single source of truth (aim introspect) and self-describing manifests in .well-known/. Built for autonomous agents, scriptable for CI, friendly for humans.

---

For AI Agents — Read This First

If you are an LLM agent, IDE assistant, or automation pipeline, start here instead of scanning the rest of this README.

One-line bootstrap

aim introspect --format json          # entire CLI schema, machine-readable

Discovery surface (all in .well-known/)

Canonical agent integration pattern

# 1. Discover — get every command, flag, type
aim introspect --format jsonld > schema.jsonld

# 2. Speak any surface
aim <subcommand> --format json        # local CLI, JSON out
curl  http://host:8080/api/v1/...     # REST (see openapi.yaml)
# or call MCP tools from mcp-manifest.json over your MCP client

Stability contract for agents

• JSON output: every read-style subcommand accepts --format json. Output schema versioned alongside the crate.
• Exit codes: 0 success · 1 general error · 2 authentication failed · 3 not found · 4 permission denied · 5 integrity / verification failure · 6 invalid input (including usage errors) · 7 configuration error · 8 compliance violation. Non-zero ⇒ failure, always. Enforced by VaultError::exit_code and pinned by tests.
• Idempotent reads: list, get, search, versions, lineage, stats, compliance, introspect, */show, */list are side-effect free.
• Destructive ops gated: delete, policy apply, gc, vault-import accept --dry-run (where applicable) or require an explicit name argument.
• Self-describing errors: error JSON includes code, message, and hint; never just a string.
• URIs: Vault resources are addressable via the aimv:// scheme — agents can pass aimv://vault/model@version between tools.
• No surprise network: the CLI never phones home except aim pull (explicit), aim cloud (explicit), and opt-in telemetry — off by default, honors DO_NOT_TRACK=1, and when enabled posts to https://telemetry.nervosys.ai/v1/events unless you point telemetry.endpoint elsewhere. Two events, no model names or paths: see docs/TELEMETRY.md.

Three-surface coverage matrix

Every one of the 29 features in AGENTS.md is reachable from all three of: CLI subcommand, REST endpoint, and MCP tool. See the parity table in agents.json for the precise mapping.

---

Table of Contents

---

Why AI Model Vault?

• Agent-first — three coequal surfaces (CLI / REST+GraphQL / MCP), one schema, self-describing via introspect and .well-known/
• Secure by default — AES-256-GCM with Argon2id KDF; aligned to CMMC 2.0 L2 and MITRE ATT&CK control families. Not a FIPS-validated module — see Security & Compliance
• Format-agnostic — auto-detect 23+ formats; convert natively between SafeTensors, PyTorch, and raw. Conversions that need a Python toolchain (→ ONNX, → TensorRT, → Core ML, → GGUF) return a runnable plan rather than a silently wrong file
• Provenance built-in — SHA-256 checksums, HMAC signatures, an automatic append-only audit log, license & pickle scanning (plus a Merkle-chained block store available as a library primitive)
• Operational — version control, retention policies, garbage collection, multi-vault, profiles, plugins, scheduled backups
• Integrated — REST + GraphQL APIs, 86 MCP tools, Python bindings, Ollama / LM Studio interop, HuggingFace / Ollama / URL pull
• Quality — 2,160+ Rust + 84 Python tests, 0 clippy warnings, fuzz targets, property-based tests, criterion benchmarks

---

Quick Start

Install

# From crates.io
cargo install ai-model-vault --features full,api

# Prebuilt binary (Linux / macOS / Windows, no toolchain needed)
# https://github.com/nervosys/AIModelVault/releases/latest
curl -sSLO https://github.com/nervosys/AIModelVault/releases/latest/download/aim-linux-amd64
curl -sSLO https://github.com/nervosys/AIModelVault/releases/latest/download/aim-linux-amd64.sha256
sha256sum -c aim-linux-amd64.sha256 && chmod +x aim-linux-amd64 && sudo mv aim-linux-amd64 /usr/local/bin/aim

# Python bindings
pip install aimodelvault

# From source
git clone https://github.com/nervosys/AIModelVault.git
cd AIModelVault
cargo build --release --features full,api
# Binary at target/release/aim (~17 MB, LTO + stripped)

full covers the storage backends but not the REST API — add api if you want aim serve. See Cargo feature flags.

30-second walkthrough

# 1. Initialize an encrypted vault
aim init

# 2. Store a model (auto-detects format)
aim store llama-7b ./model.safetensors \
  --description "Fine-tuned Llama 7B" --framework pytorch --task text-generation

# 3. Pull from HuggingFace, Ollama, or a URL
aim pull hf:mistralai/Mistral-7B-v0.1 --store --name mistral-7b
aim pull ollama:llama3 --store --name llama3

# 4. Convert SafeTensors → GGUF Q4_K_M for edge deployment
aim convert llama-7b --to-format gguf --quantization q4_k_m --validate

# 5. Sign, scan, and tag
aim sign llama-7b --identity "trainer@company.com"
aim scan llama-7b
aim tag add llama-7b production fine-tuned

# 6. Check security & compliance
aim compliance --verbose

# 7. Browse the vault interactively
aim browse

---

Feature Matrix

All features below are fully implemented, tested, and exposed via both CLI and library API unless noted.

Storage & Encryption

Version Control & Lineage

Conversion & Quantization

Safety, Signing & Validation

Provenance, Audit & Compliance

Discovery, Operations & Lifecycle

Integration & APIs

Full machine-readable surface (29 features, all CLI subcommands, ontology, OpenAPI, MCP manifest) is in .well-known/ and AGENTS.md.

---

Supported Model Formats

Conversion paths

PyTorch     → SafeTensors, ONNX, TorchScript, CoreML, MLX
SafeTensors → GGUF (q4_0, q4_k_m, q5_k_m, q8_0, f16, f32)
ONNX        → TensorRT, OpenVINO, TFLite
TensorFlow  → TFLite

See docs/PROVIDERS_FORMATS.md and FORMATS.md for full details.

---

Installation

From a registry

cargo install ai-model-vault --features full,api   # Rust CLI + library
pip install aimodelvault                           # Python bindings

Prebuilt binaries for Linux (gnu and musl), macOS (x86-64 and arm64), and Windows are attached to every release, each with a .sha256 alongside it.

From source

git clone https://github.com/nervosys/AIModelVault.git
cd AIModelVault

# Default build (Safetensors + ndarray + SQLite)
cargo build --release

# Storage backends + REST API + GraphQL
cargo build --release --features full,graphql

# Or use the helpers
./build.sh release           # Linux/macOS
.\build.ps1 release          # Windows

The release binary lives at target/release/aim (~17 MB, LTO + stripped).

Cargo feature flags

full is narrower than the name suggests: it enables the storage backends only. To get the server, ask for it explicitly:

cargo build --release --features full,api      # + aim serve
cargo build --release --features full,cloud    # + S3 / Azure

Optional system dependencies

• HashiCorp Vault / AWS / Azure — only if you use the corresponding KMS / cloud features.

---

Rust Library API Quickstart

use ai_model_vault::{Vault, VaultConfig};
use ai_model_vault::formats::{ModelFormat, ModelMetadata};

let mut vault = Vault::new(None)?;
vault.unlock(b"your-secure-passphrase".to_vec())?;

// Store
let data = std::fs::read("model.safetensors")?;
let metadata = ModelMetadata::new("llama-7b".into(), ModelFormat::Safetensors)
    .with_description("Fine-tuned Llama 7B".into())
    .with_framework("PyTorch".into())
    .with_task("text-generation".into())
    .with_parameters(7_000_000_000);
let version = vault.store_model("llama-7b", data, metadata, None)?;

// Retrieve specific version
let v2 = vault.get_model("llama-7b", Some(2))?;

// List history
for v in vault.list_versions("llama-7b") {
    println!("v{}: {} bytes", v.version, v.original_size);
}

Trait-based dependency injection (advanced)

use ai_model_vault::{VaultBuilder, AuditLogSubscriber, MetricsSubscriber};

let vault = VaultBuilder::new()
    .config(VaultConfig::default())
    .sqlite_versions(true)
    .subscriber(Box::new(AuditLogSubscriber::default()))
    .subscriber(Box::new(MetricsSubscriber::default()))
    .build()?;

CryptoProvider, BlobStore, VersionRepo, AuditSink, and EventSubscriber are all swappable traits. See docs/ARCHITECTURE_V2.md.

MCP / RAG tools

use ai_model_vault::rag::*;

let mut server = MCPServer::new();
server.register_builtin_tools()?;

let ctx = ToolContext::new()
    .with_knowledge_base("research_kb".into())
    .with_data("user_id".into(), "researcher_1".into());

let result = server.execute_tool("search_documents", &ctx, /* args */ ..)?;

Built-in tools: search_documents, add_document, chunk_text, execute_rule. Custom tools via MCPServer::register_tool(tool, executor_fn).

---

Cloud Storage

# Push, list, pull
aim cloud push  llama-7b --provider s3 --bucket my-models
aim cloud list  --provider s3 --bucket my-models
aim cloud pull  llama-7b --provider s3 --bucket my-models --remote-path llama-7b/safetensors/v1.vault

Uploads are sealed client-side (4.3.0+): AES-256-GCM under an Argon2id key derived from your vault passphrase, fresh salt per object, so the bucket holds ciphertext and can be treated as untrusted. The salt travels with the object, so a peer who knows the passphrase can pull into a different vault.

Objects pushed by a version before 4.3.0 are plaintext. pull still accepts them so nothing is stranded, but warns — re-push to seal, then delete the old object. See docs/CLOUD_STORAGE.md.

Credentials come from standard environment variables. S3 uses the normal AWS chain (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION, profiles, or an instance role). Azure takes AZURE_STORAGE_ACCOUNT plus either AZURE_STORAGE_SAS_TOKEN or Entra ID — AZURE_STORAGE_KEY is not supported, as the Azure SDK for Rust v1 has no shared-key credential.

Full guide: docs/CLOUD_STORAGE.md · CLI: docs/CLOUD_CLI.md.

---

Deployment

Running aim serve as a service. Both paths keep configuration service-scoped — nothing is written to /etc/environment or a profile script, so no other process on the host inherits the API secret or a telemetry token.

systemd

sudo ./deploy/systemd/install.sh --dry-run    # see every change first
sudo ./deploy/systemd/install.sh
sudo systemctl enable --now aim-server

Creates the aim system user and /var/lib/aim, writes /etc/aim/server.env at 0600 root-owned, generates AIM_JWT_SECRET if absent, and installs a hardened unit using EnvironmentFile= rather than Environment= — the latter is readable by any local user via systemctl show.

To configure OTLP export at install time, pass the credential as a file, never a flag (arguments are world-readable through /proc/<pid>/cmdline):

printf 'Authorization=Bearer %s' "$TOKEN" > /tmp/hdr && chmod 600 /tmp/hdr
sudo ./deploy/systemd/install.sh \
    --otlp-endpoint https://collector.example.com/otlp \
    --otlp-headers-file /tmp/hdr \
    --enable-telemetry
shred -u /tmp/hdr

Details: docs/TELEMETRY.md · docs/SECURITY_HARDENING.md.

Containers were removed in 4.5.0. The Dockerfile, the image published to ghcr.io, and the Helm chart are gone. aim ships as a static binary, a crate, and a Python wheel; run it directly or under systemd. Images already published to ghcr.io remain pullable but receive no further updates.

---

Security & Compliance

Standards

aim compliance distinguishes what it actually verified at runtime from what is asserted by design, and exits non-zero only on a real, verified failure.

Dependency security

Current status of cargo audit on master:

• ✅ rustls-webpki 0.103.13 in the primary reqwest / hyper-rustls path (RUSTSEC-2026-0098/0099/0104 patched)
• ⚠️ A handful of advisories remain in transitive dependencies (aws-smithy-http-client 1.1.12 → old rustls 0.21; sled, hdf5, azure SDK unmaintained helpers). All are documented and tracked in deny.toml with justification; cargo deny check passes.

These will clear automatically once AWS SDK upgrades to a Smithy client that uses hyper-rustls ≥ 0.27. No first-party code is affected.

Reporting vulnerabilities: security@nervosys.ai — do not open public issues. See SECURITY.md.

---

Build & Validate

# Full validation pipeline (fmt + clippy + build + test + doc)
.\validate.ps1          # Windows
./validate.sh           # Linux/macOS

# Individually
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --features full,graphql
cargo doc --no-deps --all-features

Current master status:

• ✅ cargo fmt clean
• ✅ cargo clippy — 0 warnings
• ✅ cargo build --features full,graphql — clean
• ✅ cargo test — 2,026+ tests passing across 18 suites
• ✅ cargo doc — no warnings
• ✅ cargo deny check — pass

Quality engineering

• 51 cross-module integration tests
• 11 property-based test strategies (proptest)
• 8 fuzz targets (pickle scanner, diff engine, model card parser, …)
• Criterion benchmarks with CI regression tracking (benches/)

---

Interactive Demos

# Quick 2-minute tour
.\docs\demo.ps1 -Quick           # Windows
./docs/demo.sh   --quick          # Linux/macOS

# Specific feature demos
.\docs\demo.ps1 -HuggingFace
.\docs\demo.ps1 -Security

Cargo examples

cargo run --example basic_usage             # End-to-end vault flow
cargo run --example version_control_demo    # Versioning, lineage, rollback
cargo run --example providers_formats_demo  # 23+ formats walkthrough
cargo run --example signing_demo            # HMAC signing & verification
cargo run --example scanning_demo           # Pickle safety scanning
cargo run --example diff_demo               # Tensor-level diffing
cargo run --example download_demo           # HF / Ollama / URL pull
cargo run --example interop_demo            # Ollama + LM Studio registration
cargo run --example benchmark_demo          # Benchmark metadata
cargo run --example license_scan_demo       # License detection
cargo run --example model_card_demo         # Model cards (Google/HF)
cargo run --example mcp_tools_demo          # MCP tool usage
cargo run --example rag_demo                # RAG with knowledge base
cargo run --example security_demo           # Compliance + audit
cargo run --example utilities_demo          # Archive / analyze / dedupe
cargo run --example xdg_demo                # XDG paths
cargo run --example api_demo                # REST + GraphQL
cargo run --example huggingface_demo        # HF integration

Full demo guide: docs/DEMO_GUIDE.md.

Environment variables

---

Architecture

src/
├── lib.rs / main.rs           # Library root + CLI entry
├── cli/                       # CLI dispatcher + per-command handlers
├── crypto/                    # AES-256-GCM, Argon2id, streaming
├── rag/                       # 7 RAG submodules (docs, KB, MCP, rules…)
├── vault.rs                   # Core vault logic + VaultBuilder
├── traits.rs                  # CryptoProvider, BlobStore, EventBus, URI parser
├── storage.rs                 # Local + S3/Azure backends
├── version.rs / version_sqlite.rs  # Version control (JSON + SQLite backends)
├── formats.rs                 # 23+ format detection
├── conversion.rs              # 10 format converters
├── model_card.rs              # Google / HuggingFace model cards
├── api.rs                     # REST (Axum) + GraphQL (async-graphql)
├── blockchain.rs              # Append-only audit chain with Merkle proofs
├── federation.rs              # Vector-clock peer sync
├── compliance.rs / audit.rs   # FIPS / CMMC / MITRE checks + audit log
├── download.rs                # HuggingFace / Ollama / URL pull (+ SHA-256)
├── signing.rs                 # HMAC-SHA256 signing
├── scanning.rs                # Pickle opcode scanner
├── diff.rs                    # Tensor-level diffing
├── interop.rs                 # Ollama + LM Studio
├── benchmark.rs / evaluation.rs  # Benchmark + eval metadata
├── license_scan.rs            # License detection + SPDX
├── tags.rs                    # Tags + key-value annotations
├── vault_bundle.rs            # Export / import bundles
├── gc.rs                      # Garbage collection
├── tui.rs                     # Terminal UI dashboard
├── webhooks.rs                # HTTP notification system
├── access_control.rs          # RBAC
├── kms.rs                     # AWS / Azure / HashiCorp / env
├── validation.rs              # Integrity probes
├── policies.rs                # Retention policies
├── lineage_graph.rs           # Cross-model DAG
├── plugins.rs                 # Plugin discovery + install
├── profiles.rs                # Config profiles
├── quantization.rs            # Quantization profile store
├── scheduler.rs               # Backup scheduling
├── multi_vault.rs             # Multi-vault registry
├── telemetry.rs               # Anonymous opt-in usage
├── config.rs                  # XDG-compliant config
└── python.rs                  # PyO3 bindings

Deep dives: docs/ARCHITECTURE.md · docs/ARCHITECTURE_V2.md.

---

Documentation

---

Contributing

Pull requests welcome. Please:

1. Read CONTRIBUTING.md.
2. Sign the CLA — required for all PRs.
3. Run ./validate.ps1 (or ./validate.sh) before submitting. PRs must pass fmt, clippy, tests, and docs.

---

License

Dual-licensed:

• AGPL-3.0-or-later — free for open-source use. Any modified version or network-facing service must release its source under the AGPL. See LICENSE.
• Commercial License — for proprietary, SaaS, or closed-source use without AGPL obligations. See COMMERCIAL_LICENSE.md or email licensing@nervosys.ai.

---

Support

• 📖 Documentation site · Local website/
• 💬 GitHub Discussions
• 🐛 Issue tracker
• 📧 General: dev@nervosys.ai · Security: security@nervosys.ai · Licensing: licensing@nervosys.ai

---

Built with 🦀 Rust for maximum security, performance, and reliability.