Skip to content

Codex & EdgeProof Verification

EdgeProof (edge-computing-openai) is the OpenAI Build Week verification layer for the Edge-Computing-LLM platform. It combines a deterministic Go verification CLI (edge-openai) with a repository-level Codex Agent Skill to evaluate private LLM infrastructure on Linux, k3s, and constrained NVIDIA GPUs.

Architectural Role & Boundary

EdgeProof acts as an operational verification and reasoning plane. It sits above deterministic Go checks and infrastructure layers to provide privacy-aware evidence generation and guided remediation:

flowchart TB
  subgraph OperatorLayer["Operator & AI Assistant Interface"]
    USER["Local System Operator"]
    CODEX["OpenAI Codex / AI Agent"]
    SKILL["Edge LLM Operator Codex Skill<br/>(SKILL.md / Agent Protocol)"]
  end

  subgraph VerifierEngine["Deterministic Verifier (edge-computing-openai)"]
    CLI["edge-openai CLI<br/>(Go Verification Engine)"]
    CONTRACTS["Verification Contracts<br/>(Host, K3s, GPU, Workloads, Telemetry)"]
  end

  subgraph TargetCluster["Target Infrastructure & Workloads"]
    HOST["Ubuntu Host & Kernel"]
    K3S["k3s Control Plane"]
    GPU["NVIDIA GPU & RuntimeClass"]
    LLM["Ollama & Open WebUI Workloads"]
    TELEMETRY["Prometheus & OTel Collector"]
  end

  subgraph OutputPlane["Proof & Evidence Plane"]
    SUMMARY["Console Verification Table"]
    JSON_EVIDENCE["Sanitized Evidence JSON<br/>(privacy-guaranteed)"]
    PROPOSAL["Approval-Gated Remediation Plan"]
  end

  USER -->|Invokes Skill / Command| CODEX
  CODEX -->|Executes Rules| SKILL
  SKILL -->|Calls Verifier| CLI
  CLI -->|Evaluates Contracts| CONTRACTS
  CONTRACTS -->|Inspects| HOST
  CONTRACTS -->|Inspects| K3S
  CONTRACTS -->|Inspects| GPU
  CONTRACTS -->|Inspects| LLM
  CONTRACTS -->|Inspects| TELEMETRY

  CLI --> SUMMARY
  CLI --> JSON_EVIDENCE
  CODEX -->|Analyzes Findings| PROPOSAL

Verified Infrastructure Contracts

The edge-openai CLI deterministically evaluates 13 key operational contracts across 5 platform categories:

Category Verified Contract Check Description
Host System Required Host Commands Asserts git, helm, kubectl, go, and nvidia-smi are in $PATH.
Host System NVIDIA GPU Visibility Verifies NVML interface and presence of active NVIDIA GPU device.
Kubernetes Substrate Kubernetes API Access Validates cluster connectivity and active kubeconfig context.
Kubernetes Substrate k3s Node Status Asserts local node status is Ready.
NVIDIA Substrate RuntimeClass Readiness Confirms RuntimeClass/nvidia is registered and active.
NVIDIA Substrate Allocatable GPU Resources Checks nvidia.com/gpu capacity reported in node allocatables.
NVIDIA Substrate GPU Infrastructure Namespace Verifies pods in gpu-operator namespace (gpu-operator, nfd, device-plugin, dcgm-exporter).
Workload Layer Observability Namespace Checks namespace llm-observability status and pod readiness.
Workload Layer Helm Releases Confirms active llm-observability-stack Helm deployment.
Workload Layer Ollama Engine Deployment Validates Ollama pod readiness and GGUF API responsiveness on port 11434.
Workload Layer Open WebUI StatefulSet Confirms Open WebUI container status and Redis connection on port 6379.
Telemetry Layer OTel Collector & Operator Asserts OpenTelemetry Collector pod is running and accepting metrics.
Telemetry Layer Kube-Prometheus-Stack Confirms Prometheus (9090) and Grafana (80) instances are active.

Running EdgeProof Verification

Step 1: Execute Console Verification

To run the full verification harness and view human-readable results:

cd /media/waqasm86/External1/Waqas-Projects/Project-Linux-Kubernetes-Nvidia/Project-Edge-Computing-LLM/edge-computing-openai

# Run verification suite
go run ./cmd/edge-openai verify

Sample output: 

================================================================================
                    EDGEPROOF INFRASTRUCTURE VERIFICATION
================================================================================
Timestamp: 2026-07-20T23:55:00Z
Target:    Local Single-Node k3s (waqasm86-ThinkPad-T450s)

[PASS] Host Commands: git, helm, kubectl, go, nvidia-smi available
[PASS] NVIDIA GPU: 1x NVIDIA GeForce 940M detected (Driver: 535.183.01)
[PASS] Kubernetes API: Server reachable at https://127.0.0.1:6443
[PASS] k3s Node State: Node waqasm86-ThinkPad-T450s is Ready
[PASS] RuntimeClass: 'nvidia' handler configured for containerd
[PASS] GPU Allocatable: nvidia.com/gpu = 1
[PASS] Namespace 'gpu-operator': 9/9 pods Ready (operator, nfd, device-plugin, dcgm)
[PASS] Namespace 'llm-observability': 12/12 pods Ready
[PASS] Helm Release: 'llm-observability-stack' deployed (STATUS: deployed)
[PASS] Inference Engine: Ollama pod ready (port 11434)
[PASS] User Interface: Open WebUI ready (port 8080)
[PASS] Telemetry Collector: OpenTelemetry Collector ready (ports 4317/4318)
[PASS] Monitoring Stack: Prometheus and Grafana ready

--------------------------------------------------------------------------------
Passed: 13 | Failed: 0 | Skipped: 0 | Total: 13
STATUS: VERIFIED
================================================================================

Step 2: Generate Privacy-Aware JSON Evidence

Export sanitized, privacy-guaranteed JSON evidence for audits or competition verification:

go run ./cmd/edge-openai verify --output json --file sanitized-evidence.json

Sanitized evidence schema output (sanitized-evidence.json): 

{
  "contract_version": "v1.0.0",
  "generator": "edge-openai-verifier",
  "timestamp": "2026-07-20T23:55:00Z",
  "result": "PASS",
  "summary": {
    "total_checks": 13,
    "passed": 13,
    "failed": 0,
    "skipped": 0
  },
  "checks": [
    {
      "id": "CHECK_GPU_ALLOCATABLE",
      "status": "PASS",
      "detail": "nvidia.com/gpu allocatable = 1"
    },
    {
      "id": "CHECK_RUNTIMECLASS",
      "status": "PASS",
      "detail": "RuntimeClass/nvidia present"
    }
  ],
  "privacy": {
    "prompts_included": false,
    "user_data_included": false,
    "secrets_scrubbed": true
  }
}

Approval-Gated Remediation Model

EdgeProof strictly separates diagnosis from mutation: 1. When a check fails (e.g., missing RuntimeClass/nvidia), Codex explains the failure root cause. 2. Codex formulates a specific remediation command (e.g., edge install infra). 3. Crucial Rule: Neither Codex nor EdgeProof will execute mutating commands automatically without explicit operator confirmation (--yes or interactive prompt approval).