Architecture Overview
EnvForage utilizes a client-server architecture built for fast, deterministic, and safe dependency resolution in GPU-accelerated workloads.
The Matrix Resolution Lifecycle
1. Introspection (CLI)
The CLI agent executes local OS commands to extract hardware levels (GPU model, architecture, active driver version, and CUDA capabilities).
2. Compatibility Request
Introspected attributes are packaged into a structured JSON query payload and transmitted securely to the Matrix API Engine.
3. Matrix Database Check
FastAPI resolves the optimum combinations by cross-referencing Nvidia support tables and version matching schemas.
4. Template compilation
The resolver merges framework configuration rules into secure output shell scripts, validating execution patterns against security policies.
Core Components
The CLI Agent (Local Introspection Engine)
A lightweight, dependency-free Python client that uses platform libraries to query hardware specifics like system processor counts, driver version registries, and target libraries. It verifies active shell contexts and prepares environment profiles.
The FastAPI Resolver Engine (Backend Service)
The centralized API handles version matching. Using a structured compatibility registry model, the resolver checks constraints (e.g. PyTorch v2.1 requires CUDA v11.8 or v12.1, which requires Nvidia driver >= 525) and chooses matching parameters without dependency bloat.
The Security Filter & Template Compiler
Outputs generated scripts (Bash, PowerShell, or Dockerfile). This compiler includes structural validations to filter out malicious CLI arguments, escaping variables, and locking down executable targets.
Security Sandboxing
EnvForage implements a strict sanitation filter. Any command execution paths are evaluated against an active whitelist. Shell scripts do not pull external binaries dynamically without structural signature checking.