`Vpod`

demo

`vpod`란 무엇인가요?

vpod는 신뢰할 수 없는 프로세스에 즉각적인 Linux 환경을 제공하는 가볍고 휴대성 있는 샌드박스입니다. RISC‑V 아키텍처를 사용하며 전적으로 WebAssembly 내부에서 실행됩니다.

빠른 시작 : 1초 이내에 부팅됩니다.
휴대성 : 별도의 설정 없이 어디서나 실행됩니다.
격리 : 모든 실행 상태는 WASM 샌드박스 내부에 유지됩니다.

작동 방식

vpod는 WebAssembly로 컴파일된 완전한 RISC‑V 시스템(RV64GC, 단일 vCPU)을 실행합니다. 내부에서 실제 사용자 공간을 갖춘 실제 Linux 커널을 부팅하므로 셸, 도구, 데몬이 모두 실제 하드웨어에서처럼 동작합니다.

스냅샷. vpod는 Linux를 처음부터 부팅하는 대신 스냅샷, 즉 부팅 직후 캡처된 저장된 머신 상태(CPU 레지스터, RAM, 파일시스템)를 복원합니다. 복원에는 1초도 채 걸리지 않습니다. 일시 중지는 그 반대 방식으로 동작합니다. 더티 메모리 페이지만 디스크에 다시 기록되므로 샌드박스를 일시 중지했다가 나중에 다른 프로세스에서도 재개할 수 있습니다.

사전(AOT) 번역. 순수한 명령어 단위 에뮬레이션은 느리며, WebAssembly는 런타임 JIT를 허용하지 않습니다. 따라서 스냅샷 빌드 시점에 가장 자주 실행되는 게스트 코드 경로를 RISC‑V에서 네이티브 코드로 번역하여 WASM 모듈 자체에 컴파일합니다. 런타임에 에뮬레이터는 게스트 코드가 일치하면 이러한 번역된 블록으로 디스패치하고, 일치하지 않으면 인터프리터로 폴백합니다. 이는 CPU 바운드 작업에서 약 5배의 성능 향상을 제공하며 격리에는 전혀 영향을 미치지 않습니다. 번역된 코드는 인터프리터된 코드와 동일한 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)로 설치
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으로 지원이 추가될 수 있습니다.

기여

버그 보고부터 새 디바이스 지원까지 다양한 기여를 환영합니다. 무언가 중요한 것을 만들기 전에 이슈를 열어 논의해 주세요.

사전 요구 사항

wasm32-wasip2 타겟이 포함된 Rust(최신 안정 버전): rustup target add wasm32-wasip2
SDK용 Python 3.10+
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()에서 해당 줄들의 주석을 해제하세요.

스냅샷 빌드는 AOT 패스(scripts/aot-snapshot.sh <snapshot>)를 실행할 수도 있습니다. 이 패스는 대표적인 워크로드를 추적하고 핫 블록을 번역한 다음 이를 포함하도록 에뮬레이터를 다시 빌드합니다. 시간이 꽤 걸립니다. 일상적인 개발에서는 aot-stub.sh의 스텁으로 충분합니다. 모든 것이 동일하게 작동하며 단지 느릴 뿐입니다.

풀 리퀘스트

PR 범위를 유지하세요: PR당 하나의 변경만.
fmt, clippy 및 테스트 스위트를 통과해야 합니다(CI가 세 가지를 모두 강제합니다).
에뮬레이터의 실행 또는 메모리 경로를 수정했다면 정확성을 어떻게 검증했는지 설명하세요(최소한 테스트 스위트를 사용하고, 미묘한 변경의 경우 부팅과 게스트 내 실제 워크로드 실행이 좋은 정상 동작 확인 방법입니다).

라이선스

이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

vpod v0.7.1

카테고리