# Intérprete de código
`CodeSandbox` amplía un [sandbox](https://lizard.build/es/docs/sandboxes) normal con un **kernel con estado**: las variables, las importaciones y las definiciones de funciones persisten entre llamadas, igual que en un cuaderno Jupyter. Es la herramienta adecuada cuando un agente de IA genera y ejecuta código de forma incremental.
Se inicia desde la plantilla `code-interpreter-v1` (Python 3.14 + Node.js 26, con una API de ejecución de código en el puerto 8080) y admite **Python, JavaScript y Bash** de forma predeterminada.
## Ejecutar código
```ts
import { CodeSandbox } from '@lizard-build/sdk';
// Every sandbox belongs to a project — usage is metered per project
const sandbox = await CodeSandbox.create({ project: 'my-project' }); // defaults to 'code-interpreter-v1'
await sandbox.runCode('x = 42');
const result = await sandbox.runCode('print(x * 2)');
console.log(result.stdout); // "84\n" — x survived from the previous call
await sandbox.kill();
```
`runCode(code, opts?)` devuelve un `Execution`:
| Campo | Descripción |
|---|---|
| `stdout` / `stderr` | Flujos de salida capturados |
| `results` | Resultados enriquecidos (valores y cualquier imagen / gráfico generado) |
| `error` | Un `ExecutionError` (`name`, `message`, `traceback`) si el código produjo una excepción |
| `executionCount` | Contador monótono del kernel |
## Elegir un lenguaje
El valor predeterminado es Python. Pasa `language` para una ejecución puntual en otro entorno de ejecución:
```ts
const js = await sandbox.runCode('1 + 1', { language: 'javascript' });
console.log(js.results[0].data); // "2"
await sandbox.runCode('echo "$(uname -s)"', { language: 'bash' });
```
## Salida en streaming
Para celdas de ejecución prolongada, transmite stdout/stderr a medida que se genera en lugar de esperar al resultado:
```ts
await sandbox.runCode('for i in range(5): print(i)', {
onStdout: (line) => process.stdout.write(line),
onStderr: (line) => process.stderr.write(line),
onResult: (r) => console.log('result:', r),
onError: (e) => console.error('error:', e.name, e.message),
});
```
## Contextos aislados
Un **contexto** es un espacio de nombres independiente dentro del mismo sandbox: usa uno por sesión de agente o por usuario, para que sus variables nunca entren en conflicto.
```ts
const a = await sandbox.createContext({ language: 'python' });
const b = await sandbox.createContext({ language: 'python' });
await sandbox.runCode('secret = 1', { context: a });
await sandbox.runCode('print(secret)', { context: b }); // NameError — b never saw it
await sandbox.listContexts();
await sandbox.restartContext(a); // clear all variables/state
await sandbox.deleteContext(b); // free its resources
```
Pasa **o bien** `context` **o** `language` a `runCode`, no ambos: un contexto ya tiene un lenguaje asociado.
## Crear un checkpoint de una sesión
Como `CodeSandbox` es un sandbox, [pausar y reanudar](https://lizard.build/es/docs/sandboxes/quickstart#pause-and-resume) funciona igual. Instala una pila pesada de dependencias una vez, pausa y reanuda más tarde con el estado del kernel intacto:
```ts
const sandbox = await CodeSandbox.create({ project: 'my-project' });
await sandbox.runCode('import subprocess; subprocess.run(["pip", "install", "scikit-learn"])');
const id = sandbox.sandboxId;
await sandbox.pause();
// Later — resume with packages and kernel variables already in place
const resumed = await CodeSandbox.connect(id);
const out = await resumed.runCode('import sklearn; print(sklearn.__version__)');
console.log(out.stdout);
await resumed.kill();
```
## Ver también
- [Referencia del SDK](https://lizard.build/es/docs/sandboxes/sdk-reference) — todos los métodos de `CodeSandbox` y las opciones de `runCode`.
- [Persistent Volumes](https://lizard.build/es/docs/sandboxes/volumes) — adjunta almacenamiento que perdura más allá de un único sandbox.