Introdução
O que é o Runner Codes
O Runner Codes executa código não confiável (tipicamente gerado por LLM) dentro de microVMs. O binário é o rc, e
ele trabalha de dois jeitos:
- Job descartável: uma VM nova por job, sem rede, com root read-only, destruída no fim. É o que fazem
rc run,rc shelle as rotas/api/v1/rune/api/v1/execute. - Máquina persistente: uma VM com disco próprio, que guarda o que foi instalado e gravado entre um start e outro.
É o
rc machine ..., declarável num arquivorunner.codee controlável pela API.
Código-fonte: https://github.com/andrebassi/runner-codes
As peças
- VMM: libkrun 1.19.6 com o kernel da libkrunfw 5.6.2 (Linux 6.12.109), carregada direto
como biblioteca por purego (sem cgo). Cada VM é um processo
rc vmm. - Hypervisor: Hypervisor.framework no macOS Apple Silicon; KVM (
/dev/kvm) no Linux x86_64 e aarch64. - Imagens: cada stack vira um ext4 read-only gerado a partir da imagem OCI oficial, sem
Docker. Máquinas aceitam também uma imagem OCI qualquer (
--image). - Canal com o guest: 4 bytes big-endian de tamanho + JSON, na porta vsock 5000 (protocolo).
- Latência: o pool do
rc servemantém VMs já bootadas por linguagem, cada uma usada uma vez.
O que o rc faz
| Recurso | Onde está |
|---|---|
| job efêmero pela CLI, com saída em streaming; shell interativo numa VM nova | run e shell |
máquinas: create, start, exec, shell, cp, logs, stop, delete, branch, pause, resume, sync, update, data-dir, prune | machine |
| máquina declarada num arquivo | runner.code |
rede por política (allow-host, CIDR, --block-private), redes nomeadas, ICMP, portas e faixas de portas | Rede e volumes |
volumes: diretório do host, :ro, :staged, disco da máquina, S3 | Rede e volumes |
| credenciais que a máquina usa sem ler, segredos, agente SSH, pontes de socket | Credenciais, machine |
GPU por Vulkan (Venus) e a stack llama | GPU |
tela da VM no navegador, com teclado e mouse (--display) | Tela no navegador |
| imagem ou máquina num artefato portátil | pack |
| API HTTP com pool, SSE e rotas de máquina | API HTTP, Visão geral da API |
SDKs Go (pkg/client) e Python (sdk/python) | SDKs |
| conferência do host | rc doctor, em Visão geral da CLI |
Plataformas
| Plataforma | Estado |
|---|---|
| macOS, Apple Silicon | suportado, testado de ponta a ponta e medido |
Linux x86_64 / aarch64 com /dev/kvm | suportado; o confinamento Landlock + seccomp foi testado, mas uma microVM completa no Linux ainda não foi medida |
| Windows | não suportado: a libkrun upstream não tem backend WHP, e o build para Windows falha de propósito |
Números medidos
macOS 27, Apple Silicon. No Linux ainda não houve medição.
| O quê | Valor |
|---|---|
| boot até a 1ª resposta Python (30 boots, root ext4 ro) | p50 260 ms, p95 266 ms |
| job Python pela CLI, boot frio | ~240 ms no total |
| job pela API com o pool cheio | 26–43 ms de requisição HTTP completa (uma stack) |
machine start até o guest responder | 204–244 ms |
| footprint de uma VM parada | 44 MB |
go run com o cache de build aquecido na imagem | 247 ms (sem o cache, 3,4 s) |
Detalhes e método em Desempenho e no Relatório de testes.
Linguagens
O catálogo tem 15 linguagens: Python, Node.js, Go, Rust, Java, C, C++, Ruby, PHP, Perl, Bash, sh, AWK, jq e SQLite,
mais a stack llama (llama.cpp com Vulkan). Veja Linguagens.
Próximos passos
- Início rápido: instalar a libkrun, compilar, construir a imagem, rodar o primeiro job e a primeira máquina.
- Referência para agentes: cada comando, flag, rota e erro numa página.
- Arquitetura: as peças e o caminho de um job e de uma máquina.
- Exemplos e guias: exemplos de
runner.codee guias que provam cada fluxo numa VM real. - Segurança: o que isola o código e o que ainda falta.