Sandboxes & promote

Parte do Controle de Mudanças Seguro para Agentes. Os comandos keon sandbox e keon ledger e a visão Sandboxes do console descritos aqui estão no ar — um keon recente é necessário (cli-v0.1.46+).

A Kisenon permite que você entregue a um agente de programação (Claude Code, Cursor, o seu próprio) um banco de dados que ele pode alterar livremente — sem arriscar a produção. Um sandbox é uma bifurcação por execução da sua branch com uma credencial com escopo, um log de ações ao vivo e um passo de promoção no lado do servidor. Esta página cobre o ciclo completo: captura → trabalho → promoção → aterrissagem (reversível) → prova.

Por que é seguro

Duas garantias, ambas determinísticas — nenhum LLM fica no caminho de confiança:

• O agente não pode tocar na produção. Ele se conecta com uma credencial com escopo e sem superusuário a uma bifurcação. Ele nunca porta uma credencial capaz de gravar em main. A promoção roda no lado do servidor e só aplica mudanças que já passaram no sandbox.
• Você vê exatamente o que ele fez. Cada instrução é atribuída e transmitida para um console somente leitura — o SQL real, não um resumo.

O ciclo

keon sandbox run \
  --migrate "alembic upgrade head" \
  --verify  "pytest tests/db"
# → green/red verdict + schema diff + a sandbox you can inspect

keon sandbox promote <id>   # cp applies the validated changes to main

O agente permanece no controle do ciclo; o limite é o que o torna seguro.

Captura durável

O log de ações é a fonte da verdade para o promote, então ele precisa estar completo. Cada sandbox carrega um capture_state — ok ou lost. Se a captura for algum dia comprometida, o estado muda para lost e permanece ali: um sandbox perdido não pode promover (409 sandbox_capture_lost) e nunca aplica silenciosamente uma mudança parcial. Não há autocorreção — descarte-o e reexecute o trabalho em um sandbox novo. keon sandbox get / list mostram a saúde da captura.

Promote: autoatendimento ou aprovado por humano

Cada projeto escolhe um promote_mode:

Ensaio do raio de destruição

Antes de promover, você pode pedir à plataforma para medir o que o promote faria — níveis de lock reais, durações de retenção de lock reais, contagens de linhas reais — em vez de adivinhar a partir do texto da instrução:

keon sandbox dry-run <id>

A plataforma reexecuta o conjunto exato de instruções do sandbox contra duas bifurcações descartáveis de vida curta do pai — uma no HEAD atual do pai (onde locks, durações e linhas são medidos) e uma no ponto de bifurcação do sandbox (a baseline de divergência) — depois destrói ambas. Ela nunca toca em main, e o agente nunca recebe uma credencial para nenhuma das bifurcações. O ensaio é consultivo: ele produz o relatório, nunca bloqueia um promote.

Ele também responde à pergunta que um diff estático não consegue: a realidade se moveu sob o agente? Qualquer instrução que dê erro, ou que afete um número diferente de linhas, no HEAD do pai do que dava no ponto de bifurcação é exposta como um conflito — por exemplo, um UPDATE ... WHERE id = 2 cuja linha-alvo foi excluída em main após a bifurcação.

O relatório concluído carrega:

Os endpoints são POST /v1/sandboxes/{id}/dry-run (inicia uma execução assíncrona, 202) e GET /v1/sandboxes/{id}/dry-run (o registro mais recente). Um ensaio com falha carrega um error_code legível por máquina (capture_fence_failed, incomplete_capture, fork_failed, compute_unreachable, replay_infra_failed, timeout). O painel Blast radius na página de detalhes do sandbox renderiza o mesmo relatório no console.

Desfazer um promote

Um promote é reversível. Antes de o cp aplicar as instruções validadas em main, ele ancora o estado exato pré-promote da branch pai (um LSN). Um comando reverte a branch para essa âncora:

keon sandbox undo <id>   # restore the parent branch to its pre-promote state

A string de conexão do pai fica inalterada — os clientes reconectam ao mesmo endpoint. Undo é uma ação de proprietário/administrador; chaves de capacidade de agente são recusadas (403 scope_insufficient), porque um undo descarta o que quer que tenha aterrissado na branch após a âncora.

keon sandbox get <id> carrega um objeto undo — undoable, restored_lsn, undone_at e um blocked_reason quando ele não pode rodar (superseded_by_later_promote, already_undone). Undo tem como alvo apenas o promote mais recente, e rejeita com 409 (sandbox_not_promoted, undo_anchor_missing, undo_anchor_invalidated) uma vez que a âncora se foi. Ele permanece disponível enquanto a âncora for válida e dentro da sua retenção de storage — não há uma contagem regressiva separada.

Undo restaura por LSN: ele reverte tudo após a âncora, não apenas a mudança promovida — incluindo gravações diretas e sessões de agente posteriores naquela branch. Veja Armadilhas comuns.

Migrações emitidas

Todo promote aterrissado emite uma migração SQL up/down determinística — sem LLM, gerada a partir da mudança de esquema capturada e validada em ida e volta em uma bifurcação descartável antes de ser oferecida. Busque-a:

keon sandbox migration <id> --out ./migrations --wait

O artefato carrega o SQL up e down (files[], cada um com um role), uma flag coverage (full ou partial), down_fidelity, quaisquer uncovered_seqs, um resultado de validation e um sha256. Os estados terminais são validated, validation_failed, emission_failed e no_schema_changes. A v1 emite sql; GET /v1/sandboxes/{id}/migration (e .../migration/files/{role}) o servem. A emissão roda depois que o promote aterrissa e nunca o bloqueia ou reverte — um promote apenas de dados simplesmente reporta no_schema_changes.

Ledger assinado

Todo promote e undo acrescenta um registro assinado e encadeado por hash a um ledger por projeto — uma atestação verificável offline do que mudou. A verificação não precisa de rede e não confia na Kisenon:

keon ledger list --project <id>          # the chain (reports chain_ok)
keon ledger export <id> --out att.json   # one attestation document
keon ledger verify att.json              # offline; exit 0 iff valid
keon ledger keys --save                  # pin the signing keys you trust

keon ledger verify verifica as assinaturas Ed25519 e a cadeia de hash e reporta falhas precisas (signature_invalid, statement_chain_mismatch, seq_gap, key_untrusted, chain_broken, …); a confiança é tri-estado (trusted / untrusted / unverified). Rotas: GET /v1/sandboxes/{id}/ledger, GET /v1/projects/{projectId}/ledger, GET /v1/ledger/keys.

Se o cp não tem uma chave de assinatura configurada, os promotes ainda têm sucesso, mas ficam não assinados (ledger_enabled: false) — a assinatura não é incondicional.

O que um sandbox não é

• Não é um sandbox de código — ele dá escopo ao seu banco de dados, não ao processo do agente.
• Não é um juiz LLM — captura, replay e revisão são deterministicamente byte a byte.

Experimente

Experimente em kisenon.com e veja o quickstart.