# NEPHIS SOVEREIGN CLOUD: COMPLETE SPECIFICATION & AGENT INTERFACE Version: 2.1.0-PROD Architecture: Tri-Titan Speculative Execution Substrate Principal Architect: Mohit Raj Deo (https://mohitrajdeo.in) ## 1. Unified Control Plane - Canonical Ingress: https://nephis.theeducode.com - Direct Origin (Port 8080): http://13.126.155.62:8080 - Claim Agent Key: POST https://nephis.theeducode.com/v1/auth/claim-agent-key - Account Telemetry & Preferences: GET /v1/auth/me, PATCH /v1/auth/me - FinOps Alert Test: POST /v1/account/notifications/test - Supported Runtimes: 60+ compilers, Firecracker KVM microVMs, PostgreSQL 16.3 + pgvector 0.7.0 --- ## 2. Subsystem Specifications ### Titan 1: ESCHATON (Stateless High-Throughput Execution & Online Judging) - Gateway Entrypoints: - `POST /v1/submissions?wait=true` — Synchronous code run (< 4ms Void microkernel) - `POST /v1/submissions/fast-batch` — Up to 50 parallel testcases executed concurrently in < 38ms - `POST /v1/submissions/complexity` — Hardware instruction counting & Big-O complexity analyzer - `POST /v1/submissions/sanitize` — ASan + UBSan memory safety & leak detection - `POST /v1/submissions/dbms` — Ephemeral in-memory PostgreSQL/MySQL database sandbox - `POST /v1/submissions/fileio` — Named file sandbox evaluation with tmpfs - `POST /v1/submissions/special-judge` — Custom testlib validator execution - `GET /v1/submissions/:token` — Asynchronous submission status & output - `GET /v1/languages` — Supported compilers & runtimes catalog - Key Benchmarks: - AST Preflight Parse: 1.18 ms - C++ Warm Compile (`shmparse`): 3.4 ms - Python / Bash Cold Eval: 38.2 ms - Maximum Sustained Ingress: 74,200 RPS - Execution Guarantees: - Seccomp-bpf syscall quarantine - Zero-credit auto-refund on backend retry or execution timeout - Judge0 CE v1.13.0 wire compatibility ### Titan 2: THANATON (Hardware-Isolated Linux MicroVM Sandboxes) - Gateway Entrypoints: - `POST /v1/sandboxes` — Provision KVM hardware sandbox (vcpus, memory_mb) - `POST /v1/sandboxes/:id/exec` — Execute arbitrary bash pipeline with root capabilities - `POST /v1/sandboxes/:id/freeze` — Suspend microVM to 0.00% vCPU stasis (180 KB footprint) - `POST /v1/sandboxes/:id/resume` — Instant sub-6ms lazy unfreeze via UFFD - `DELETE /v1/sandboxes/:id` — Instant destruction and storage reclamation - Key Benchmarks: - Cold Kernel Guest Boot: 4.82 ms - Stasis Memory Consumption: 180 KB - Lazy Wake Latency: < 6 ms - Egress Security: AWS IMDS (169.254.169.254) strictly filtered via eBPF - Workload Scope & Web Deployment: - Ephemeral compute sandboxes, compiler workers, deterministic agent loops, and persistent web application deployments. - Native public routing with automated SSL wildcard subdomains (`*.theeducode.com`), staging previews (`*-staging-thanaton.theeducode.com`), and custom domain mapping (`POST /api/v1/projects/:id/domains`). Deploy via `thanaton deploy ./app` or REST. ### Titan 3: MNEMON-DB (Zero-Copy PostgreSQL 16 Database Branching) - Gateway Entrypoints: - `POST /v1/databases/branch` — Create Copy-on-Write child branch in < 30ms - `POST /v1/databases/sql` — Execute arbitrary SQL query on any branch - `GET /v1/databases` — List branches, connection pools, and WAL positions - `POST /v1/databases/freeze` — Scale tenant database to 0.00% CPU - `POST /v1/databases/resume` — Wake database in < 200 µs - `POST /v1/databases/reset` — Rewind branch to base state in < 10 ms - `POST /v1/projects/:id/vector/quantize` — HNSW-PQ vector quantization & disk-spill indexing - `POST /v1/projects/:id/migration/import` — Zero-downtime Neon/Supabase CDC import & cutover - `POST /v1/projects/:id/schema/reconcile` — 3-way schema reconciliation before branch merge - `GET /v1/projects/:id/advisor` — Slow query diagnostics & index advisor - `GET /v1/projects/:id/lineage` — Visual DAG branch lineage tree - `POST /v1/projects/:id/pitr` — Point-in-time recovery WAL replay - `GET /rest/v1/` & `GET /db/rest/v1/` — Drop-in PostgREST RESTful HTTP proxy - Key Benchmarks: - Branch Provisioning Latency: 28.4 ms - Initial Physical Disk Cost: 0 Bytes (XFS reflink block pointer duplication) - Extensions Included: `pgvector` 0.7.0, `pg_trgm`, `uuid-ossp`, `hstore` - Transaction Durability: Cold boot disk recovery with dynamic cluster attach --- ## 3. Tool Invocations for AI Agents ### Python SDK Usage (`nephis`): ```python from nephis import Nephis client = Nephis(api_key="mrd_live_YOUR_KEY") # 1. Run untrusted code in 38ms res = client.execute(language="python", code="print(2**100)") print(res.stdout) # 2. Spawn microVM sandbox vm = client.sandboxes.create(memory_mb=256) out = vm.exec("ls -la / && uname -a") print(out.stdout) vm.destroy() # 3. Branch PostgreSQL 16 database in 30ms branch = client.db.branch(parent="main", name="test-branch") rows = branch.query("SELECT * FROM pg_catalog.pg_tables LIMIT 5;") print(rows) branch.destroy() ``` ### Unified CLI Suite (`nephisctl`, `thanaton`, `mnemon`, `eschatonctl`): ```bash # 1. Authenticate with single environment variable export NEPHIS_API_KEY="mrd_live_YOUR_KEY" # 2. Inspect identity and compute credits python sdk/cli/nephisctl whoami python sdk/cli/nephisctl balance # 3. Fast Code Execution in 38ms python sdk/cli/nephisctl run "print('hello')" --language python # 4. MicroVM Sandbox Orchestration python sdk/cli/thanaton up --runtime microvm --memory-mb 512 python sdk/cli/thanaton exec sbx-101 -- uname -a python sdk/cli/thanaton sleep sbx-101 python sdk/cli/thanaton wake sbx-101 # 5. Full-Stack Web Application Deployment python sdk/cli/thanaton deploy ./my-web-app --name "my-app" --port 5000 --prod # 6. Serverless PostgreSQL 16 30ms Branching & SQL python sdk/cli/mnemon branch prod_org preview_experiment --parent main python sdk/cli/mnemon sql prod_org "SELECT * FROM users LIMIT 5;" python sdk/cli/mnemon reset prod_org preview_experiment ``` ### Model Context Protocol (MCP Server): ```bash npx -y nephis-mcp-server ``` --- ## 4. Engineering Attribution & Legal - Architect: Mohit Raj Deo - Portfolio: https://mohitrajdeo.in - GitHub: https://github.com/mohitrajdeo - LinkedIn: https://www.linkedin.com/in/mohitrajdeo/ - Contact: mohit@mohitrajdeo.in