Vpod

आरंभ करें • दस्तावेज़ीकरण • समस्याएँ • योगदान

vpod क्या है ?

vpod एक हल्का, पोर्टेबल सैंडबॉक्स है जो एक अविश्वसनीय प्रोसेस को तुरंत Linux वातावरण प्रदान करता है। यह RISC‑V आर्किटेक्चर का उपयोग करता है और पूरी तरह से WebAssembly के अंदर चलता है।

• तेज़ स्टार्टअप : एक सेकंड से भी कम समय में बूट होता है।
• पोर्टेबल : बिना किसी सेटअप की आवश्यकता के कहीं भी चलता है।
• आइसोलेटेड : सारा निष्पादन स्टेट WASM सैंडबॉक्स के अंदर ही रहता है।

यह कैसे काम करता है

एक vpod WebAssembly में संकलित एक संपूर्ण RISC‑V सिस्टम (RV64GC, सिंगल vCPU) चलाता है। इसके अंदर एक वास्तविक Linux कर्नेल और एक वास्तविक यूज़रस्पेस बूट होता है, इसलिए शेल, टूल्स और डेमॉन सभी वैसे ही व्यवहार करते हैं जैसे वे वास्तविक हार्डवेयर पर करते हैं।

स्नैपशॉट। Linux को शुरू से बूट करने के बजाय, एक vpod स्नैपशॉट पुनर्स्थापित करता है: बूट के ठीक बाद कैप्चर की गई एक सहेजी गई मशीन स्टेट (CPU रजिस्टर, RAM, फाइल सिस्टम)। इसे पुनर्स्थापित करने में एक सेकंड से काफी कम समय लगता है। सस्पेंड उल्टे क्रम में उसी तरह काम करता है, केवल डर्टी मेमोरी पेज ही डिस्क पर वापस लिखे जाते हैं, इसलिए आप सैंडबॉक्स को रोक सकते हैं और बाद में उसे फिर से शुरू कर सकते हैं, यहाँ तक कि किसी अन्य प्रोसेस से भी।

Ahead-of-time (समय-पूर्व) अनुवाद। शुद्ध निर्देश-दर-निर्देश एम्युलेशन धीमा है, और WebAssembly रनटाइम JIT की अनुमति नहीं देता। इसलिए स्नैपशॉट निर्माण के समय, सबसे अधिक उपयोग किए जाने वाले गेस्ट कोड पथों का RISC‑V से नेटिव कोड में अनुवाद किया जाता है, जिसे WASM मॉड्यूल में ही संकलित किया जाता है। रनटाइम पर जब गेस्ट कोड मेल खाता है तो एम्यूलेटर इन अनुवादित ब्लॉकों में डिस्पैच करता है, और जब मेल नहीं खाता तो इंटरप्रेटर पर वापस आ जाता है। CPU-बाउंड कार्यों पर यह लगभग 5x का लाभ देता है, और आइसोलेशन पर इसका शून्य प्रभाव पड़ता है: अनुवादित कोड उन्हीं MMU और मेमोरी जाँचों से गुजरता है जिनसे इंटरप्रेटेड कोड गुजरता है।

WASI सीमा। WASM कंपोनेंट होस्ट से केवल WASI 0.2 के माध्यम से संवाद करता है। गेस्ट को होस्ट के फाइल डिस्क्रिप्टर, सॉकेट या मेमोरी कभी नहीं दिखती: फाइल सिस्टम एक्सेस स्पष्ट रूप से माउंट किए गए डायरेक्ट्री के माध्यम से होता है, और नेटवर्किंग कंपोनेंट के अंदर एक यूज़र-मोड नेटवर्क स्टैक के माध्यम से होती है जो होस्ट से केवल साधारण आउटबाउंड सॉकेट माँगता है। बाकी सब कुछ (गेस्ट कर्नेल, प्रोसेस, मेमोरी) WASM लीनियर मेमोरी के अंदर रहता है और उसी के साथ समाप्त हो जाता है।

RV64GC स्पेसिफिकेशन

G (सामान्य-प्रयोजन एक्सटेंशन)

• I : आधार 64-बिट इंटीजर निर्देश सेट।
• M : हार्डवेयर गुणा और भाग, हैशिंग और क्रिप्टोग्राफी के लिए उपयोगी।
• A : थ्रेड-सेफ प्रोग्राम के लिए एटॉमिक ऑपरेशन।
• F/D : सिंगल और डबल-प्रिसिजन फ्लोटिंग-पॉइंट, वैज्ञानिक कंप्यूटिंग और ML इन्फ्रेंस के लिए उपयुक्त।

C (कंप्रेस्ड निर्देश) कोड का आकार 30% तक कम करता है, जिससे इंस्ट्रक्शन फेच की गति और मेमोरी दक्षता में सुधार होता है। यह हमारे मेमोरी-सीमित WASM वातावरण में एक पूर्ण Linux यूज़रस्पेस चलाते समय महत्वपूर्ण है।

[!NOTE] V (वेक्टर) एक्सटेंशन लागू नहीं किया गया है। RVV निर्देश एम्युलेटेड RISC-V के रूप में निष्पादित होंगे; होस्ट CPU के लिए कोई SIMD पासथ्रू नहीं है। V जोड़ने से वेक्टराइज़्ड वर्कलोड के लिए बिना किसी प्रदर्शन लाभ के एम्युलेशन ओवरहेड बढ़ जाएगा।

आरंभ करना

Python SDK

pip install vpod

from vpod import Sandbox

# Run a command
sandbox = Sandbox.create()
result = sandbox.commands.run("whoami")
print(result.stdout)  # root
sandbox.close()

# Persistent session — state preserved across calls
with Sandbox.create() as sandbox:
    sandbox.commands.run("export API_KEY=secret")
    result = sandbox.commands.run("echo $API_KEY")
    print(result.stdout)  # secret

# Python REPL — variables persist
with Sandbox.create() as sandbox:
    sandbox.code.run("import requests")
    sandbox.code.run("data = [1, 2, 3]")
    result = sandbox.code.run("print(sum(data))")
    print(result.text)  # 6

[!IMPORTANT] Sandbox.create() की पहली कॉल डिफ़ॉल्ट स्नैपशॉट (alpine) डाउनलोड करती है और यदि वह पहले से मौजूद नहीं है तो उसे स्थानीय रूप से कैश कर लेती है।

CLI

curl -fsSL https://install.vpod.sh | sh

या PowerShell (windows) के माध्यम से इंस्टॉल करें

root@kitploit:~

irm https://install.vpod.sh | iex

# Pull a snapshot
vpod pull alpine:latest

# Start an interactive shell
vpod

दस्तावेज़ीकरण

Vpod दस्तावेज़ीकरण देखें।

सीमाएँ

• एम्युलेशन ओवरहेड: WebAssembly के अंदर कोई हार्डवेयर वर्चुअलाइज़ेशन नहीं है, इसलिए सारा गेस्ट कोड एम्युलेटेड होता है। ओवरहेड पूरी तरह से वर्कलोड पर निर्भर करता है: I/O-बाउंड और नेटवर्क-बाउंड कार्य नेटिव गति के करीब चलते हैं, जबकि भारी CPU-बाउंड कार्य AOT अनुवाद के साथ भी काफी धीमे चलते हैं। यदि आपका वर्कलोड अधिकतर "टूल चलाना, फाइल पढ़ना, API कॉल करना" है, तो आपको अंतर महसूस नहीं होगा।
• GPU एक्सेस नहीं: CUDA, Metal और हार्डवेयर ML एक्सेलरेटर उपलब्ध नहीं हैं। भविष्य में wasi-nn के साथ समर्थन जोड़ा जा सकता है।

योगदान

बग रिपोर्ट से लेकर नए डिवाइस समर्थन तक, सभी योगदानों का स्वागत है। कुछ भी महत्वपूर्ण बनाने से पहले चर्चा करने के लिए एक issue खोलें।

पूर्वापेक्षाएँ

• Rust (नवीनतम स्थिर संस्करण) wasm32-wasip2 टारगेट के साथ: rustup target add wasm32-wasip2
• Python 3.10+ SDK के लिए
• Zig (0.16) और bsdtar, केवल तभी आवश्यक हैं जब आप स्नैपशॉट स्वयं बनाते हैं

विकास सेटअप

# One-time: generate the AOT stub (a fresh clone has no translated blocks)
./scripts/aot-stub.sh

# Build the WASM component (library + CLI)
./scripts/build-wasm.sh

# Install the host CLI
cargo install --path crates/vpod

# Install the Python SDK in dev mode
pip install -e "sdks/python[dev]"

टेस्ट चलाना

CI इन्हें हर PR पर चलाता है, इसलिए push करने से पहले इन्हें चलाएँ:

cargo fmt --all -- --check                        # formatting
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all                                  # Rust tests

# Python SDK integration tests (needs the WASM library in place)
cp target/wasm32-wasip2/release/vpod_wasi_lib.wasm sdks/python/vpod/
pytest sdks/python/tests/ -v -m integration

स्नैपशॉट बनाना

प्रोजेक्ट registry.vpod.sh से पहले से निर्मित Alpine स्नैपशॉट का उपयोग करता है, इसलिए आपको सामान्यतः इसकी आवश्यकता नहीं होती। स्थानीय रूप से एक बनाने के लिए:

./scripts/build-default-snapshot.sh   # dist/alpine-3.23.0-256mb.snap
./scripts/build-data-snapshot.sh      # 512 MB variant with numpy/pandas/scipy

[!IMPORTANT] स्थानीय रूप से निर्मित स्नैपशॉट का उपयोग करने के लिए, crates/vpod/src/main.rs में resolve_snapshot() की पंक्तियों को अनकमेंट (uncomment) करें।

स्नैपशॉट बिल्ड AOT पास (scripts/aot-snapshot.sh <snapshot>) भी चला सकते हैं, जो एक प्रतिनिधि वर्कलोड को ट्रेस करता है, हॉट ब्लॉकों का अनुवाद करता है, और उन्हें शामिल करके एम्यूलेटर का पुनर्निर्माण करता है। इसमें कुछ समय लगता है; रोज़मर्रा के विकास के लिए aot-stub.sh का स्टब ही पर्याप्त है, सब कुछ वैसे ही काम करता है, बस धीमा।

पुल रिक्वेस्ट

• PR को केंद्रित रखें: प्रति PR एक ही बदलाव।
• fmt, clippy और टेस्ट सूट पास होना चाहिए (CI तीनों को लागू करता है)।
• यदि आप एम्यूलेटर के निष्पादन या मेमोरी पथों को छूते हैं, तो बताएँ कि आपने शुद्धता को कैसे मान्य किया (न्यूनतम रूप से टेस्ट सूट; सूक्ष्म बदलावों के लिए बूट के साथ-साथ गेस्ट में एक वास्तविक वर्कलोड चलाना एक अच्छी सैनिटी जाँच है)।

लाइसेंस

यह प्रोजेक्ट Apache License 2.0 के अंतर्गत लाइसेंस प्राप्त है। विवरण के लिए LICENSE फ़ाइल देखें।