Exemplos e guias

Exemplos

Em examples/ ficam os exemplos dos SDKs, cada um testado contra um rc serve local no macOS 27 (Apple M1 Pro). Para declarar uma máquina num arquivo versionado, veja o formato do runner.code.

Exemplo	O que mostra	Estado
sdk-go	o SDK Go: job e ciclo de vida de máquina contra um rc serve	funciona
sdk-python	o mesmo com o SDK Python	funciona
desktop-claude	desktop XFCE com Claude Code e Firefox num runner.code, criado e conferido pelo SDK Go	funciona
desktop-claude-agent	tarefas ao Claude dessa VM de três jeitos: claude -p, digitada na janela, pela API de tela	funciona

Guias

Cada pasta de examples/guides/ é um guia de uso do rc, com um README.md que explica o fluxo e um run.sh que prova o que o guia diz numa VM de verdade e sai com o número de falhas.

task build
task guides                        # todas as pastas
task guides DIRS="pack teardown"   # algumas

Na rodada de 21/10/2026 (macOS 27, Apple M1 Pro): 9 pastas, 175 conferências, 0 falhas.

Guia	O que prova
install	boot de verdade: marcador do guest e kernel diferente do host
throwaway-machine	repo :ro, saída gravável, sem rede; rede um host por vez; --block-private, loopback do host
pack	imagem e máquina num artefato; o marcador vem junto com a origem apagada; cache reaproveitado
teardown	parar, apagar, provar limpo; Ctrl-C e kill -9 no CLI não deixam VM viva
credentials	o valor nunca entra na VM (busca com contraprova); interceptação só no host da binding; 403 na URL
branch-and-checkpoint	checkpoint de disco com retenção e trava, restauração de qualquer geração, pause/resume, filhas de uma fonte aquecida, checkpoint exportado como pack
gpu-cuda	não há CUDA: doctor, CLI, runner.code e API dizem não, com o motivo, sem criar nada
local-api	rc serve com corpos JSON de ciclo de vida; exitCode no corpo; SSE uma linha por evento; campo desconhecido recusado
reference	uma etapa por tema com prova (runner.code, redes nomeadas, nested, limitações, sockets, display, posse de arquivo, S3) e os temas fora do escopo, com o motivo

O lib.sh da pasta reúne o que todo run.sh usa: o formato do rc machine ls, o processo de uma VM (rc vmm --spec <dir>/spec.json), o diretório da máquina (rc machine data-dir) e a lista vazia (No machines found).

Runbook

Além dos guias, o docs/runbook.md é a sequência de teste à mão, passo a passo, com o resultado esperado de cada um; task runbook executa os mesmos passos e reprova se algum sair diferente (146 conferências, 0 falhas em 24/10/2026).