Vpod

Primeiros passos • Documentação • Issues • Contribuindo

O que é um vpod ?

Um vpod é um sandbox leve e portátil que oferece a um processo não confiável um ambiente Linux instantâneo. Ele usa arquitetura RISC‑V e é executado inteiramente dentro do WebAssembly.

• Inicialização rápida : Inicializa em menos de um segundo.
• Portátil : Executa em qualquer lugar sem necessidade de configuração.
• Isolado : Todo o estado de execução permanece dentro dos sandboxes WASM.

Como funciona

Um vpod executa um sistema RISC‑V completo (RV64GC, uma única vCPU) compilado para WebAssembly. Dentro dele, inicializa um kernel Linux real com um userspace real, então shells, ferramentas e daemons se comportam exatamente como fariam em hardware real.

Snapshots. Em vez de inicializar o Linux do zero, um vpod restaura um snapshot: um estado de máquina salvo (registradores de CPU, RAM, sistema de arquivos) capturado logo após a inicialização. Restaurar um leva bem menos de um segundo. A suspensão funciona da mesma forma, ao contrário: apenas páginas de memória sujas são gravadas de volta no disco, permitindo pausar um sandbox e retomá-lo depois, até mesmo de outro processo.

Tradução antecipada (AOT). A emulação puramente instrução por instrução é lenta, e o WebAssembly descarta um JIT em tempo de execução. Então, no momento da construção do snapshot, os caminhos de código convidado mais "quentes" são traduzidos de RISC‑V para código nativo que é compilado dentro do próprio módulo WASM. Em tempo de execução, o emulador despacha para esses blocos traduzidos quando o código convidado corresponde e volta para o interpretador quando não corresponde. Isso gera aproximadamente 5x em trabalho com uso intenso de CPU, sem nenhum efeito sobre o isolamento: o código traduzido passa pelas mesmas verificações de MMU e memória que o código interpretado.

O limite do WASI. O componente WASM fala com o host exclusivamente por meio do WASI 0.2. O convidado nunca vê descritores de arquivo, sockets ou memória do host: o acesso ao sistema de arquivos passa por diretórios explicitamente montados, e a rede passa por uma pilha de rede em modo usuário dentro do componente que apenas solicita ao host sockets de saída simples. Todo o resto (kernel convidado, processos, memória) vive dentro da memória linear do WASM e morre com ela.

Especificação RV64GC

G (Extensões de propósito geral)

• I : Conjunto base de instruções inteiras de 64 bits.
• M : Multiplicação e divisão em hardware, úteis para hashing e criptografia.
• A : Operações atômicas para programas thread-safe.
• F/D : Ponto flutuante de precisão simples e dupla, adequado para computação científica e inferência de ML.

C (Instruções compactadas) Reduz o tamanho do código em 30%, melhorando a velocidade de busca de instruções e a eficiência de memória. Isso é importante ao executar um userspace Linux completo dentro do nosso ambiente WASM com restrição de memória.

[!NOTE] A extensão V (vetorial) não está implementada. As instruções RVV seriam executadas como RISC-V emulado; não há passagem SIMD para a CPU host. Adicionar V aumentaria a sobrecarga de emulação sem nenhum benefício de desempenho para cargas de trabalho vetorizadas.

Primeiros passos

SDK Python

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] A primeira chamada a Sandbox.create() baixa o snapshot padrão (alpine) e o armazena em cache localmente se ainda não estiver presente.

CLI

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

Ou instale via PowerShell (windows)

root@kitploit:~

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

# Pull a snapshot
vpod pull alpine:latest

# Start an interactive shell
vpod

Documentação

Visite a documentação do Vpod.

Limitações

• Sobrecarga de emulação: Não há virtualização de hardware dentro do WebAssembly, então todo o código convidado é emulado. A sobrecarga depende inteiramente da carga de trabalho: trabalho limitado por E/S e por rede roda próximo à velocidade nativa, enquanto trabalho pesado limitado por CPU roda visivelmente mais devagar, mesmo com tradução AOT. Se a sua carga for majoritariamente "executar uma ferramenta, ler um arquivo, chamar uma API", você não notará.
• Sem acesso à GPU: CUDA, Metal e aceleradores de ML em hardware não estão disponíveis. O suporte pode ser adicionado no futuro com wasi-nn.

Contribuindo

Contribuições são bem-vindas, desde relatórios de bugs até suporte a novos dispositivos. Abra uma issue para discutir qualquer coisa substancial antes de implementá-la.

Pré-requisitos

• Rust (última versão estável) com o alvo wasm32-wasip2: rustup target add wasm32-wasip2
• Python 3.10+ para o SDK
• Zig (0.16) e bsdtar, necessários apenas se você mesmo criar snapshots

Configuração de desenvolvimento

# 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]"

Executando testes

A CI executa estes em todo PR, então execute-os antes de enviar:

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

Criando snapshots

O projeto usa snapshots Alpine pré-construídos de registry.vpod.sh, então normalmente você não precisa disso. Para criar um localmente:

./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] Para usar um snapshot construído localmente, descomente as linhas em resolve_snapshot() em crates/vpod/src/main.rs.

As compilações de snapshot também podem executar o passe AOT (scripts/aot-snapshot.sh <snapshot>), que rastreia uma carga de trabalho representativa, traduz os blocos "quentes" e reconstrói o emulador com eles incorporados. Isso demora um pouco; o stub de aot-stub.sh é suficiente para o desenvolvimento diário, tudo funciona igual, apenas mais devagar.

Pull requests

• Mantenha os PRs focados: uma alteração por PR.
• fmt, clippy e a suíte de testes devem passar (a CI exige os três).
• Se você mexer nos caminhos de execução ou memória do emulador, diga como validou a corretude (no mínimo a suíte de testes; para mudanças sutis, uma inicialização mais uma carga de trabalho real no convidado é um bom teste de sanidade).

Licença

Este projeto está licenciado sob a Apache License 2.0. Veja o arquivo LICENSE para detalhes.