Sandboxes & promote

Parte de Agent-Safe Change Control. Los comandos keon sandbox y keon ledger y la vista de Sandboxes de la consola que se describen aquí están en vivo — se requiere un keon reciente (cli-v0.1.46+).

Kisenon le permite entregar a un agente de programación (Claude Code, Cursor, el suyo propio) una base de datos que puede modificar libremente — sin arriesgar producción. Un sandbox es un fork por ejecución de su rama con una credencial acotada, un registro de acciones en vivo y un paso de promoción del lado del servidor. Esta página cubre el bucle completo: captura → trabajo → promoción → aterrizaje (reversible) → demostración.

Por qué es seguro

Dos garantías, ambas deterministas — ningún LLM se sitúa en la ruta de confianza:

• El agente no puede tocar producción. Se conecta con una credencial acotada que no es de superusuario a un fork. Nunca posee una credencial capaz de escribir en main. La promoción se ejecuta del lado del servidor y solo aplica los cambios que ya pasaron en el sandbox.
• Usted ve exactamente lo que hizo. Cada sentencia se atribuye y se transmite a una consola de solo lectura — el SQL real, no un resumen.

El bucle

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

El agente mantiene el control del bucle; el límite es lo que lo hace seguro.

Captura duradera

El registro de acciones es la fuente de verdad para la promoción, así que tiene que estar completo. Cada sandbox lleva un capture_state — ok o lost. Si la captura se ve comprometida en algún momento, el estado cambia a lost y permanece ahí: un sandbox perdido no puede promocionar (409 sandbox_capture_lost) y nunca aplica un cambio parcial en silencio. No hay autorreparación — descártelo y vuelva a ejecutar el trabajo en un sandbox nuevo. keon sandbox get / list muestran la salud de la captura.

Promoción: autoservicio o con aprobación humana

Cada proyecto elige un promote_mode:

Simulación de radio de impacto

Antes de promocionar, puede pedir a la plataforma que mida lo que haría la promoción — niveles de bloqueo reales, duraciones reales de retención de bloqueos, recuentos de filas reales — en lugar de adivinar a partir del texto de la sentencia:

keon sandbox dry-run <id>

La plataforma reproduce el conjunto exacto de sentencias del sandbox contra dos forks desechables de corta duración del padre — uno en el HEAD actual del padre (donde se miden bloqueos, duraciones y filas) y otro en el punto de fork del sandbox (la línea base de divergencia) — y luego destruye ambos. Nunca toca main, y el agente nunca recibe una credencial a ninguno de los dos forks. La simulación es consultiva: produce el informe, nunca bloquea una promoción.

También responde a la pregunta que un diff estático no puede: ¿se movió la realidad bajo el agente? Toda sentencia que da error, o afecta a un número distinto de filas, en el HEAD del padre respecto a lo que hizo en el punto de fork se expone como un conflicto — p. ej. un UPDATE ... WHERE id = 2 cuya fila objetivo se eliminó en main después del fork.

El informe completado lleva:

Los endpoints son POST /v1/sandboxes/{id}/dry-run (inicia una ejecución asíncrona, 202) y GET /v1/sandboxes/{id}/dry-run (el registro más reciente). Una simulación fallida lleva un error_code legible por máquina (capture_fence_failed, incomplete_capture, fork_failed, compute_unreachable, replay_infra_failed, timeout). El panel Blast radius en la página de detalle del sandbox renderiza el mismo informe en la consola.

Deshacer una promoción

Una promoción es reversible. Antes de que cp aplique las sentencias validadas a main, ancla el estado exacto de la rama padre previo a la promoción (un LSN). Un comando revierte la rama a ese ancla:

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

La cadena de conexión del padre no cambia — los clientes se reconectan al mismo endpoint. Deshacer es una acción de propietario/administrador; las claves con capacidad de agente se rechazan (403 scope_insufficient), porque un deshacer descarta todo lo que aterrizó en la rama después del ancla.

keon sandbox get <id> lleva un objeto undo — undoable, restored_lsn, undone_at, y un blocked_reason cuando no puede ejecutarse (superseded_by_later_promote, already_undone). Deshacer apunta solo a la promoción más reciente, y rechaza con 409 (sandbox_not_promoted, undo_anchor_missing, undo_anchor_invalidated) una vez que el ancla desaparece. Permanece disponible mientras el ancla sea válida y dentro de su retención de almacenamiento — no hay una cuenta atrás aparte.

Deshacer restaura por LSN: revierte todo lo posterior al ancla, no solo el cambio promovido — incluidas las escrituras directas y las sesiones de agente posteriores en esa rama. Consulte Errores comunes.

Migraciones emitidas

Cada promoción aterrizada emite una migración SQL up/down determinista — sin LLM, generada a partir del cambio de esquema capturado y validada de ida y vuelta en un fork desechable antes de ofrecerse. Obténgala:

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

El artefacto lleva el SQL up y down (files[], cada uno con un role), un indicador coverage (full o partial), down_fidelity, cualesquiera uncovered_seqs, un resultado de validation y un sha256. Los estados terminales son validated, validation_failed, emission_failed y no_schema_changes. v1 emite sql; GET /v1/sandboxes/{id}/migration (y .../migration/files/{role}) lo sirven. La emisión se ejecuta después de que la promoción aterriza y nunca la bloquea ni la revierte — una promoción de solo datos simplemente informa no_schema_changes.

Ledger firmado

Cada promoción y cada deshacer añade un registro firmado y encadenado por hash a un ledger por proyecto — una atestación verificable sin conexión de lo que cambió. La verificación no necesita red y no confía en 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 comprueba las firmas Ed25519 y la cadena de hash e informa fallos precisos (signature_invalid, statement_chain_mismatch, seq_gap, key_untrusted, chain_broken, …); la confianza es de tres estados (trusted / untrusted / unverified). Rutas: GET /v1/sandboxes/{id}/ledger, GET /v1/projects/{projectId}/ledger, GET /v1/ledger/keys.

Si cp no tiene una clave de firma configurada, las promociones aún tienen éxito pero quedan sin firmar (ledger_enabled: false) — la firma no es incondicional.

Qué no es un sandbox

• No es un sandbox de código — acota su base de datos, no el proceso del agente.
• No es un juez LLM — la captura, la reproducción y la revisión son deterministas a nivel de byte.

Pruébelo

Pruébelo en kisenon.com y consulte el inicio rápido.