🏗️ Container & Enclave Architecture

An executive-level overview of how the VEOX server is packaged, deployed, and secured — designed for CTOs, CISOs, and platform engineers evaluating VEOX for production use.

Architecture Overview

The VEOX server ships as a single Docker container that runs entirely on your infrastructure. No data ever leaves your network. The container implements a multi-layer security architecture called the Aegis Enclave.

flowchart TD
    subgraph VPC [Your Infrastructure On-Premise / VPC]
        subgraph Container [VEOX Enclave Container - Single Image]
            C[Aegis Supervisor Controller PID 1]
            C -->|Starts| PG[PostgreSQL 15 - Unix Socket]
            C -->|Starts| API[FastAPI on :8090]
            C -->|Starts| DOCS[Docs on :8080]
            C -->|Decrypts| F[core_free.enc<br/>API + Free Engine]
            C -->|Decrypts| P[vip_premium.enc<br/>Pro Engine]

            API -->|Serves| DASH[Command Center Dashboard]
            API <-->|WebSocket<br/>500ms telemetry| DASH

            subgraph Workers [Aegis Sandboxed Workers]
                direction LR
                W1[Worker 1]
                W2[Worker 2]
                WN[Worker N]
            end

            API <==>|Encrypted IPC<br/>ChaCha20-Poly1305| Workers
            Workers -->|Results| PK[PaperKit PDF Builder]
        end
    end
    Client[Your Python Client] ===>|HTTP :8090| API

    classDef container fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5;
    classDef worker fill:#ef4444,stroke:#991b1b,color:#fff;
    classDef encrypted fill:#8b5cf6,stroke:#5b21b6,color:#fff;
    classDef dashboard fill:#38abbb,stroke:#0e7490,color:#fff;

    class Container container;
    class W1,W2,WN worker;
    class F,P encrypted;
    class DASH dashboard;

Single-Container Design

VEOX deliberately packages everything into one container rather than a microservice mesh. This is an intentional design choice for security-sensitive deployments:

Design Decision	Rationale
Single image	Eliminates network-level attack surface between services
No external dependencies	No databases, message queues, or cloud services required
Self-contained runtime	Python environment, ML libraries, and seed data all pre-packaged
Deterministic	Same image, same behavior — no config drift between services

What's Inside the Container

veox-enclave-server:latest
├── /app/env/                  Python 3.14.3 + 80 packages (scikit-learn, XGBoost, LightGBM, PyTorch, …)
├── /app/bootstrap.py          Entrypoint — decrypts enclaves, launches Controller
├── /app/Private/doug/src/
│   ├── controller.py          Aegis Supervisor (PID 1, manages all subsystems)
│   └── api/
│       ├── server.py          FastAPI server + Command Center dashboard + WebSocket telemetry
│       ├── evolution_router.py  Evolution jobs, datasets, PaperKit, snapshots (13 endpoints)
│       ├── dashboard.py       Real-time telemetry collector (CPU/mem/disk/net)
│       └── dashboard_html.py  Self-contained HTML/CSS/JS Command Center
├── /app/startup_banner.py     Branded boot diagnostics with system health checks
├── /app/core_free.enc         Encrypted: API + Free engine + seed data
├── /app/vip_premium.enc       Encrypted: Pro engine (requires license activation)
├── /app/Private/aegis/        Aegis sandbox (RLIMIT enforcement, encrypted IPC)
└── /app/docs/dist/            Pre-built MkDocs documentation site

Dual-Encryption Enclaves

All proprietary code is encrypted at build time and decrypted only at runtime in memory. The container filesystem never contains plaintext source code.

Free Enclave (core_free.enc)Pro Enclave (vip_premium.enc)

Contains the core API, application layer, free evolution engine, human-authored seed data (848 algorithmic primitives), and all algorithm configurations.

core_free.enc (encrypted at build)
└── Decrypted at runtime by bootstrap.py
    ├── API endpoints (FastAPI)
    ├── Free evolution engine (SimpleEvolution)
    ├── Config Compiler
    ├── Algorithm configs (7 families)
    └── Human seed data (848 stages)

Contains the Pangea multi-island evolution engine, VIP evaluators, AI-generated seed data (2,213 additional stages), and PaperKit publication engine. Requires license activation.

vip_premium.enc (encrypted at build, requires license key)
└── Decrypted only after license validation
    ├── Pangea engine (multi-island, oracle-driven)
    ├── VIP evaluators (7 domain-specific)
    ├── GrandMaster scoring overlay (LCB)
    ├── Generative seed data (2,213 AI-authored stages)
    └── PaperKit (automated research paper generation)

Build Pipeline

Chainguard Base Image

The build stage uses Chainguard Python images (cgr.dev/chainguard/python:latest-dev), which are:

Minimal: Only essential packages — no shell utilities, no package managers in final image
Hardened: Built with security-first defaults, non-root by default
Signed: Cryptographically signed and verifiable via Sigstore/cosign
CVE-free (at release): Chainguard continuously patches base images, targeting zero known CVEs

Multi-Stage Build

flowchart TD
    subgraph S1 [Stage 1: Builder - Chainguard Python]
        direction TB
        B1[1. Install Pixi package manager]
        B2[2. Install ML dependencies prod/build/test]
        B3[3. Copy source code & seed data]
        B4[4. Strip VIP IP from wheel source]
        B5{5. AUDIT: VIP Leaks?}
        B6[6. Build Python Wheel public SDK]
        B7[7. Encrypt core_free.enc]
        B8[8. Encrypt vip_premium.enc]

        B1 --> B2 --> B3 --> B4 --> B5
        B5 -->|Pass| B6
        B5 -->|Fail| Fail[Build Fails ❌]
        B4 --> B7 & B8
    end

    subgraph S2 [Stage 2: Runtime - Python 3.11 Slim]
        direction TB
        R1[1. Copy prod Pixi prefix]
        R2[2. Copy encrypted blobs]
        R3[3. Copy bootstrap.py & Aegis]
        R4[4. Configure tmpfs IPC]
        R5[5. Set HEALTHCHECK]
        R6[6. Run as nonroot]

        R1 & R2 & R3 --> R4 --> R5 --> R6
    end

    S1 ==>|Final Artifacts Only| S2

    classDef audit fill:#f59e0b,stroke:#b45309,color:#fff;
    class B5 audit;

IP Protection Audit

The build pipeline includes an automated IP leak detector:

# Build fails immediately if any VIP/Generative files are in the public wheel
test $(find /tmp/wheel_src -iname "*vip*" -o -iname "*Generative*" | wc -l) -eq 0 \
  || (echo "❌ VIP IP LEAK DETECTED" && exit 1)

This ensures VEOX Pro intellectual property never ships in the public Python SDK package.

Aegis Supervisor

The Aegis supervisor is the security orchestration layer that manages worker processes. It runs as PID 1 inside the container and enforces all security policies.

Worker Lifecycle

flowchart TD
    B[Bootstrap PID 1]
    B --> D[Decrypt enclaves to aegis_storage]
    B --> A[Start FastAPI Server]

    A --> E[Receive Evolution Job]
    E --> S[Spawn Sandboxed Worker]

    subgraph Sandbox [Aegis Security Sandbox]
        RL[Apply RLIMIT<br/>Mem/CPU/FDs]
        Net[Isolate Network<br/>No Outbound]
        IPC[Establish Encrypted IPC<br/>ChaCha20-Poly1305]
        Eval[Execute Pipeline Evaluation]

        RL --> Net --> IPC --> Eval
    end

    S --> Sandbox

    Sandbox -.-> M[Heartbeat Monitor every 5s]
    M -->|Crash/Stall| R[Auto-replace worker]
    Sandbox -->|80% CPU| Retire[Graceful Retirement]

    classDef secure fill:#4ade80,stroke:#166534,color:#000;
    class Sandbox secure;

Resource Limits per Worker

Resource	Limit	Purpose
Memory	512 MB (configurable)	Prevents OOM from crashing the host
CPU time	300 seconds	Prevents infinite loops
File descriptors	256	Limits filesystem access
Network	Fully isolated	No outbound connections from workers
IPC	Encrypted tmpfs sockets	Prevents data interception

Why Workers Are Sandboxed

Workers execute user-submitted and evolved code — arbitrary Python pipelines that could be malicious or buggy. The sandbox prevents:

Threat	Mitigation
Memory exhaustion (malloc bomb)	RLIMIT_AS hard cap
CPU exhaustion (infinite loop)	RLIMIT_CPU hard cap
Network exfiltration (data theft)	Network namespace isolation
Disk filling	RLIMIT_FSIZE + read-only filesystem
Code injection into supervisor	JSON-only return channel + encrypted IPC

Deployment

Quick Start

docker run -d \
  --name veox-enclave-server \
  -p 8090:8090 \
  714044927654.dkr.ecr.us-east-2.amazonaws.com/doug/single_enclave/veox-enclave-server:latest

Health Check

The container includes a built-in health check:

curl http://localhost:8090/health
# → {"status": "healthy", "timestamp": "..."}

Environment Variables

Variable	Default	Description
`AEGIS_WORKER_MEM_MB`	`512`	Per-worker memory limit
`AEGIS_WORKER_CPU_SEC`	`300`	Per-worker CPU time limit
`AEGIS_WORKER_MAX_FDS`	`256`	Per-worker file descriptor limit
`AEGIS_RESERVED_CORES`	`1`	Cores reserved for supervisor
`AEGIS_HEARTBEAT_SEC`	`5`	Worker health check interval
`AEGIS_STALL_TIMEOUT`	`120`	Seconds before killing stalled worker
`AEGIS_API_PORT`	`8090`	API listening port

Data Flow Summary

For CTO/CISO review — this is how your data moves through the system:

flowchart LR
    subgraph Local [Your Machine / Infrastructure]
        direction TB
        subgraph Script [Your Python Script]
            Code[evolver = VeoxEvolver<br/>evolver.fit]
        end

        subgraph Enclave [Docker : VEOX Enclave]
            direction TB
            API[FastAPI]
            Mem[(Container Memory)]
            Evo[Evolution Engine]

            API -->|Stores Data| Mem
            Mem --> Evo
            Evo -->|Returns Pipeline| API
        end

        Script ===>|HTTP POST localhost:8090| API
        API ===>|HTTP Payload| Script
    end

    Cloud((External Cloud / Internet))
    Enclave -.-x|Blocked by Sandbox| Cloud

    classDef blocked fill:#ef4444,stroke:#991b1b,color:#fff;
    class Cloud blocked;

Important

Zero data exfiltration by design. Your datasets, models, and results never leave your infrastructure. Workers are network-isolated at the kernel level — even a compromised pipeline cannot phone home.

PDF generation: PaperKit builds publication-ready PDFs inside the enclave. You trigger the build with POST /api/v1/evolution/jobs/{id}/build_paper and download the result with GET /api/v1/evolution/jobs/{id}/paper_pdf. No LaTeX or PDF tools are required on your machine.