Metadata-Version: 2.4
Name: stasis-vm
Version: 0.1.0
Summary: Sub-millisecond zero-device hardware micro-VMM and secure sandbox client for AI agents
Author-email: Vikhilan Swamy <contact@stasisvm.com>
Project-URL: Homepage, https://github.com/stasisvm/stasis-vm
Project-URL: Bug Tracker, https://github.com/stasisvm/stasis-vm/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Security
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# StasisVM (`stasis-vm`)

**Sub-millisecond, zero-device `/dev/kvm` micro-VMM for untrusted Python AI agent execution.**  
`0.09 ms` cold boot · `2.25 µs` execution latency · `< 1.00 µs` hardware `TZCNT` dirty-page reset · 64-bit Monotonic IFC Taint Lattice.

[![PyPI version](https://img.shields.io/pypi/v/stasis-vm.svg)](https://pypi.org/project/stasis-vm/)
[![SDK License: MIT](https://img.shields.io/badge/SDK%20License-MIT-blue.svg)](LICENSE)
[![Arch: x86_64 Linux KVM](https://img.shields.io/badge/arch-x86__64%20%2Fdev%2Fkvm-success.svg)]()

---

## 4-Line Quickstart (`pip install stasis-vm`)

```python
import stasis_vm

sb = stasis_vm.Sandbox(timeout_ms=50)
result = sb.eval("""
import math
area = math.pi * (42 ** 2)
print(f"Computed circle area: {area:.2f}")
""")

print(f"Exit: {result.exit_code} | Duration: {result.execution_time_us:.2f}µs")
print(result.output)
```

---

## Why StasisVM Exists

Traditional sandboxes force a broken trade-off for RL code verification (GRPO/SWE-bench) and autonomous data agents:
* **Firecracker / E2B / Modal (`80–150 ms` boot):** Emulate legacy motherboard hardware (`VirtIO` shared rings, PCI/MMIO) and boot a 15M-line Linux kernel just to run 20 lines of Python.
* **WebAssembly / Pyodide:** Cannot `dlopen()` native `x86_64` C/C++/Fortran `.so` wheels (`PyTorch`, `OpenBLAS`, `Polars`), traps on CPython function-pointer casts without `fpcast-emu`, and caps SIMD at 128-bit `v128`.
* **Docker / `nsjail` / `gVisor`:** Share the Host Ring-0 kernel or pay heavy Go syscall-interception overhead while leaving ambient POSIX network sockets wide open to prompt-injected data exfiltration.

**StasisVM strips away BIOS, 16-bit Real Mode, Guest Linux, and VirtIO completely.** It boots a pre-warmed CPython 3.12 Zygote (`STASIS02` with PEP 683 Immortal Refcounts + `gc.freeze()`) directly into 64-bit Long Mode (`CR0.PG=1, EFER.LMA=1`).

---

## Bare-Metal Architecture

```text
+-----------------------------------------------------------------------------------+
| HOST USER SPACE (Pinned Rust Worker Thread — Zero GIL Contention)                 |
|                                                                                   |
|  +-----------------------------+   < 1.00µs Reset    +-------------------------+  |
|  | Clean Zygote Template       | ------------------> | KVM EPT Dirty Bitmap    |  |
|  | (PEP 683 Immortal + Frozen) |  TZCNT / BLSR Copy  | (4KB Page Granularity)  |  |
|  +-----------------------------+                     +-------------------------+  |
|                                                                                   |
|  +-----------------------------------------------------------------------------+  |
|  | 64 MB Contiguous Guest Physical Arena (2MB HugePage Identity Map: GVA==GPA) |  |
|  | [0x01000: PML4/GDT] [0x10000: TX Aperture] [0x20000: RX Aperture] [0x200000: Code] |
|  +-----------------------------------------------------------------------------+  |
|         |                                                         ^               |
|         | `out 0x80, eax` (Synchronous Halt: vCPU Frozen)         | `VMENTRY`     |
|         v                                                         |               |
|  +-----------------------------------------------------------------------------+  |
|  | Semantic Capability Broker & Preemption Watchdog (`immediate_exit` + SIGURG)|  |
|  |  1. Generational Handle Check (`gen << 32 | slot`) -> Unforgeable C-List    |  |
|  |  2. Deep-Copy / `OP_BULK_XFER` Scatter-Gather (Zero Shared-Ring TOCTOU)     |  |
|  |  3. 64-Bit Monotonic IFC Lattice (`L_sandbox |= L_source` <= `L_sink`)      |  |
|  +-----------------------------------------------------------------------------+  |
+-----------------------------------------------------------------------------------+
```

---

## Verified Benchmarks (`x86_64` Linux `/dev/kvm`)

Reproduce locally via `./scripts/package_release.sh` or run the benchmark suite:

| Runtime / Sandbox Engine | Cold Boot / Spawn | Python Exec RTT | Memory Reset | Native `.so` Wheels (`AVX-512`) | Taint Exfiltration Protection |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **StasisVM (`KvmEngine`)** | **`0.09 ms` (90 µs)** | **`2.25 µs` (149k/s)** | **`< 1.00 µs`** | **100% Native `x86_64`** | **Hardware Port `0x80` IFC Lattice** |
| Microsoft Hyperlight (Wasm) | `1.00 – 2.00 ms` | `~45.00 µs` | `~150.00 µs` | No (`wasm32` only) | Host Function Whitelist |
| Firecracker / E2B Micro-VM | `80.00 – 150.00 ms` | `~1,200.00 µs` | `~15,000.00 µs` | 100% Native `x86_64` | None (Ambient Guest Network) |
| Docker / `gVisor` (`runsc`) | `150.00 – 400.00 ms` | `~850.00 µs` | Container Destroy | 100% Native `x86_64` | None (Shared Kernel / POSIX) |

*Note: Infinite guest loops (`while True: pass` or `jmp $`) are preempted by the host `immediate_exit` hardware watchdog in **4.0 µs** (HTTP 504) with zero worker starvation.*

---

## Packaging & License Split

To keep StasisVM sustainable as an independent systems project without forcing users onto a managed cloud API:
* **`stasis-sdk`, `stasis-bench`, and Integrations (`MIT License`):** All Python bindings, benchmark harnesses, and agent integrations in this repository are open-source under the MIT License.
* **`stasis-daemon` & `stasis.so` (`Free Developer Tier + Commercial Fleet License`):** Distributed as stripped, LTO-hardened native Linux binaries inside the PyPI wheel.
  * **Free Forever (No Key Required):** Local development (`--unsafe-dev-no-isolation` Ring-3 `SIGSEGV` harness) and up to **2 concurrent `/dev/kvm` workers** on Linux bare metal.
  * **Production Bare-Metal Nodes:** Unlock up to 500 concurrent `/dev/kvm` sandboxes per server with an offline Ed25519 node license (`$299/mo` Starter up to 16 cores · `$699/mo` Scale up to 64 cores · `$1,999/mo` Cluster).
