El SDK utiliza por defecto el endpoint alojado. El mismo código se ejecuta contra tu propio clúster o un servidor sandbox independiente configurando `MITOS_BASE_URL`. La clave se resuelve a partir del argumento o de `MITOS_API_KEY` y nunca se registra.

### 2. Crear un sandbox y ejecutar código```python
import mitos

sb = mitos.create("python")                  # Ready microVM sandbox (~27 ms warm-claim)
print(sb.exec("echo hello").stdout)          # hello

# Files and a stateful code interpreter hang off the same flat handle.
sb.files.write("/workspace/plan.txt", "draft")
print(sb.run_code("import math; math.sqrt(144)").text)   # 12.0

El cliente asíncrono refleja la misma superficie: `await mitos.aio.create("python")` devuelve un `AsyncDirectSandbox` con los mismos `exec` / `run_code` / `files` / `create_pty` / `fork` / `terminate`.

Los métodos bloqueantes `exec` y `run_code` funcionan en el husk predeterminado. El exec en streaming (`sb.exec(..., on_stdout=...)`), los procesos en segundo plano (`sb.exec_background(...)`) y el PTY interactivo (`sb.create_pty()`) se ejecutan actualmente en la ruta del motor y se están incorporando al husk predeterminado; `run_code` devuelve un `KernelUnavailable` de fallo cerrado hasta que el kernel se incluya en la imagen base del husk.

### Ejecútalo a tu manera

Mismo motor, misma API, más puntos de entrada. La profundidad está a un clic en [la documentación](https://mitos.run/docs).

**Cada idioma, dos modos.** Cada SDK habla la misma API REST de servidor sandbox en **modo directo** (independiente o alojado), y cada uno también tiene **modo clúster** (un `AgentRun` que controla los CRD `mitos.run/v1` a través de la API de Kubernetes). La nomenclatura del pool predeterminado es byte por byte idéntica en los seis.

| Idioma | Instalación | Directo | Clúster | Documentación del SDK |
|---|---|---|---|---|
| Python | `pip install mitos-run` | síncrono + asíncrono | `AgentRun` | [sdk/python](https://github.com/mitos-run/mitos/blob/HEAD/sdk/python) |
| TypeScript | `npm i @mitos/sdk` | sí | `AgentRun` | [sdk/typescript](https://github.com/mitos-run/mitos/blob/HEAD/sdk/typescript/README.md) |
| Go | `go get github.com/mitos-run/mitos/sdk/go` | tipado, compatible con `errors.Is` | `AgentRun` | [sdk/go](https://github.com/mitos-run/mitos/blob/HEAD/sdk/go/README.md) |
| Ruby | gema (solo stdlib) | sí | `AgentRun` | [sdk/ruby](https://github.com/mitos-run/mitos/blob/HEAD/sdk/ruby/README.md) |
| Rust | caja (bloqueante) | sí | `AgentRun` | [sdk/rust](https://github.com/mitos-run/mitos/blob/HEAD/sdk/rust/README.md) |
| Java | JDK 17 (solo stdlib) | sí | `AgentRun` | [sdk/java](https://github.com/mitos-run/mitos/blob/HEAD/sdk/java/README.md) |

El SDK de Go se distribuye en su propio módulo anidado (`github.com/mitos-run/mitos/sdk/go`), por lo que importarlo nunca incorpora el controlador a tu compilación.

**¿Autoalojamiento? Mismo código.** El chart de Helm despliega la misma puerta de enlace que ejecuta el servicio alojado, por lo que el inicio rápido anterior funciona sin cambios en tu propio clúster: apunta `MITOS_BASE_URL` a tu puerta de enlace y mantén todo lo demás. Alojado y autoalojado son una misma experiencia; solo difieren la URL y quién lo opera.

**Control nativo de Kubernetes, cuando lo desees.** Para equipos de plataforma que gestionan pools de forma declarativa (GitOps, automatización con ámbito RBAC, operadores), la ruta de dos niveles `AgentRun` omite la puerta de enlace y controla los CRD `mitos.run/v1` directamente a través de la API de Kubernetes:```python
from mitos import AgentRun

c = AgentRun()                                   # kubeconfig or in-cluster; autodetected
sb = c.sandbox("python", ready=True)             # claims a warm sandbox, waits Ready
print(sb.exec("python -c 'print(40 + 2)'").stdout)   # 42

fork_a, fork_b = sb.fork(2)                       # fork against shared warmed state
sb.terminate()

`mitos dev up` levanta un plano de control local de un solo comando en un motor simulado para desarrollo en modo clúster. Un servidor MCP (`mitos-mcp`) expone las sandboxes como herramientas MCP para cualquier agente que hable MCP, y una [habilidad de agente](https://github.com/mitos-run/mitos/blob/HEAD/skills/mitos/SKILL.md) enseña a los agentes conscientes de habilidades el flujo de trabajo. La matriz de instalación completa (script, Homebrew, deb/rpm, scoop/winget, checksums) está en [mitos.run/docs/install](https://mitos.run/docs/install).

**Sumérgete en el agente que ya usas.** Cada adaptador es un delgado shim sobre las mismas operaciones nativas (`exec`, `run_code`, `files`, `fork`), sin dependencia estricta del paquete del framework: Claude Code y opencode (servidor MCP + habilidad de agente), el OpenAI Agents SDK, el Claude Agent SDK, LangChain / deepagents, Vercel AI SDK / Pydantic AI / AutoGen / LlamaIndex (MCP estándar) y shims de migración de "cambia un import" para equipos que abandonan las nubes de [E2B](https://mitos.run/docs/migrating-from-e2b) o [Daytona](https://mitos.run/docs/migrating-from-daytona). El [centro de integraciones](https://github.com/mitos-run/mitos/blob/HEAD/docs/integrations/README.md) indexa cada ruta.

**Instala el operador.**```bash
kubectl apply -k deploy/

**Dónde se ejecuta.** El único requisito del nodo es `/dev/kvm` más la etiqueta `mitos.run/kvm=true`, por lo que mitos se instala en cualquier clúster de Kubernetes con nodos KVM de metal desnudo o virtualización anidada:

| platform | KVM node | guide |
|---|---|---|
| Metal desnudo (Talos, Hetzner) | `/dev/kvm` nativo | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) (referencia de primera clase) |
| AWS / EKS | Grupos de nodos `*.metal` o con virtualización anidada | chart genérico hoy; guía por nube es el issue [#919](https://github.com/mitos-run/mitos/issues/919) |
| GKE | grupos de nodos con virtualización anidada | chart genérico hoy; guía por nube es [#919](https://github.com/mitos-run/mitos/issues/919) |
| Azure / AKS | tamaños de VM con capacidad de virtualización anidada | chart genérico hoy; guía por nube es [#919](https://github.com/mitos-run/mitos/issues/919) |

El chart y los CRDs son idénticos en todos ellos; solo difiere el grupo de nodos que proporciona `/dev/kvm`.

## Por qué Mitos

Los arneses de agentes necesitan entornos rápidos y aislados donde los agentes lean y escriban archivos, instalen paquetes y ejecuten código no confiable. Cada opción existente impone un compromiso: velocidad sin propiedad, aislamiento sin bifurcación, nativo de Kubernetes sin inicios en caliente, o durabilidad bloqueada dentro de la nube de otro.

- **Bifurcar en vivo una VM en ejecución.** Bifurcación copy-on-write de N vías de una microVM en vivo: las hijas comparten las páginas de memoria de la padre hasta que escriben, por lo que cada bifurcación aterriza en un entorno cálido y listo. Ramifica un agente en muchos intentos paralelos.
- **Activación de claim en caliente de ~27 ms.** Las microVM de Firecracker se restauran desde una instantánea de memoria en la clase de decenas de milisegundos: P50 ~27 ms en el nodo de referencia de metal desnudo, reproducible desde [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh).
- **Código abierto, autoalojable, nativo de Kubernetes.** Hasta donde sabemos, el único runtime que hace las tres cosas. Usted maneja todo el ciclo de vida a través de CRDs declarativos (`mitos.run`).

Dos formas de ejecutarlo:

- **Autoalojado (hoy):** cualquier clúster de Kubernetes con nodos KVM. Sus datos nunca salen de su infraestructura. El metal desnudo (Talos + Hetzner) es la plataforma de referencia de primera clase.
- **Alojado (en progreso):** el mismo motor y API operados por nosotros, para equipos que quieren milisegundos sin gestionar nodos.

> Existen dos rutas de motor. La **ruta nativa de pods de husk es la predeterminada**: cada VM se ejecuta en su propio pod no privilegiado, y el pod de origen de husk toma una instantánea de su VM en ejecución para que N pods hijos la restauren mediante CoW. La **ruta raw-forkd** ejecuta bifurcaciones en el motor en proceso de forkd. Todo aquí se ejecuta en el husk predeterminado a menos que se marque explícitamente `engine path`.

Los sandboxes no son pods. Los mecanismos de Kubernetes con ámbito de pod (NetworkPolicy, ResourceQuota, PSA) gobiernan el pod de husk, no la carga de trabajo dentro de la microVM; el sandbox es la VM, no el pod de husk, y donde proporcionamos un equivalente se documenta como nuestro. Las rutas completas de datos de claim y exec y el diagrama de componentes están en [mitos.run/docs/architecture](https://mitos.run/docs/architecture).

## Benchmarks

Cada número aquí es reproducible desde [`bench/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/) en hardware KVM real; no se publica nada que un lector no pueda regenerar (la regla del proyecto de no-claims-no-verificados). Cada fila nombra lo que mide y el comando exacto que lo reproduce. Los datos completos por ejecución y el contexto de hardware están en [`bench/results/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/).

### Tiempo hasta interactivo alojado, contra el conjunto de pares de ComputeSDK

El tiempo hasta interactivo (TTI) es la única cifra que es comparable directamente con el [benchmark público de ComputeSDK](https://github.com/computesdk/benchmarks) contra el que se mide cada proveedor de sandbox alojado: el reloj comienza en `create()` y se detiene cuando un comando realmente se ha EJECUTADO dentro del sandbox y ha regresado.

| provider | TTI P50 | measures |
|---|---|---|
| northflank | 95.9 ms | ComputeSDK published |
| **mitos** | **96.8 ms** | nuestra herramienta, `api.mitos.run` |
| daytona | 136.2 ms | ComputeSDK published |
| e2b | 365.6 ms | ComputeSDK published |

Reproduzca nuestro número y la tabla de pares (los números de pares se leen del commit inmutable que ComputeSDK publicó, no re-ejecutados por nosotros):```sh
MITOS_API_KEY=... python3 bench/tti-latency.py 100        # our TTI, N=100
python3 bench/peer-tti.py --date 2026-07-09 \
  --ref 3eddee1a972bd49aea56fd6c16d238ca0a45dece            # the peer table

Método completo y hardware en [bench/README.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/README.md); resultados en [2026-06-19-bare-metal-fork-exec.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/2026-06-19-bare-metal-fork-exec.md) y [2026-06-21-kvm-perf-correctness.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/2026-06-21-kvm-perf-correctness.md).

### Activación warm-claim (el motor, no el viaje completo)

La activación warm-sandbox del propio motor (carga de snapshot + handshake de corrección de fork + guest-ready) es P50 ~27 ms en el nodo de referencia bare-metal, reproducible desde [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh). Este es un número más pequeño y diferente al TTI alojado de extremo a extremo anterior; citar la cifra del motor contra el número de create-API de un competidor sería un error de categoría, por lo que los mantenemos separados.

## Características

La ruta pod-native de husk es la predeterminada. Algunas capacidades se ejecutan hoy solo en la ruta `engine path` raw-forkd y están marcadas, con un enlace al issue de seguimiento.

### Velocidad

| Capacidad | Lo que obtienes | Documentación |
|---|---|---|
| Activación warm-claim | P50 ~27 ms en el nodo de referencia bare-metal (carga de snapshot + handshake de corrección de fork + guest-ready); ~6-16 ms de restauración de snapshot; ~3 MiB de memoria marginal por fork mediante compartición de páginas CoW | [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md) |
| Pools pre-snapshotted | Imágenes OCI aplanadas a ext4 rootfs y calentadas con tus pasos `init` antes de hacer snapshot, por lo que no hay arranque en frío al reclamar | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| Compartición de memoria CoW | Pagas por páginas únicas entre forks, no por copias | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| Distribución direccionada por contenido | Los forks obtienen solo los fragmentos sha256 faltantes de un titular a través de mTLS; las reconstrucciones envían deltas bajo un contrato de compatibilidad de versiones | [docs/snapshot-distribution.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/snapshot-distribution.md) |

### Aislamiento

| Capacidad | Lo que obtienes | Documentación |
|---|---|---|
| Aislamiento de hardware por sesión | Un kernel dedicado por sandbox (KVM/Firecracker); en el husk por defecto cada VM se ejecuta en su propio pod no privilegiado y restringido por PSA, que es el límite por VM | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Sin herencia silenciosa de secretos | Los forks en vivo de sandboxes que contienen secretos se rechazan a menos que se opte explícitamente; las credenciales se inyectan en el momento de la reclamación a través de vsock, nunca se hornean en snapshots | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Egreso denegado por defecto | Un filtro nftables de denegación por defecto dentro del pod en su propia netns (independiente de CNI), con un bloqueo incondicional de metadatos de nube (169.254.169.254) y una lista de permitidos por plantilla por IP:puerto y por nombre a través de un proxy DNS dentro del pod. Verificado de extremo a extremo en un clúster KVM real; el invitado no puede influir en la aplicación | [mitos.run/docs/networking](https://mitos.run/docs/networking) |
| Cifrado en reposo | Contenedores LUKS2 por alcance con destrucción criptográfica y envoltura de sobre KMS (detrás de `--enable-encryption`, fallo cerrado); claves respaldadas por HSM y alcance por espacio de trabajo son seguimientos | [docs/encryption.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/encryption.md) |

### DX del agente

| Capacidad | Lo que obtienes | Documentación |
|---|---|---|
| Exec bloqueante | stdout y código de salida correctos a través de la API del sandbox | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| Exec y PTY en streaming | stdout/stderr incremental, procesos en segundo plano y un terminal WebSocket interactivo con control de token (`engine path`) | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| Intérprete de código | `run_code` con un kernel con estado y resultados multi-MIME enriquecidos, en todos los SDK y el servidor MCP; `KernelUnavailable` con fallo cerrado hasta que el kernel se incluya en la imagen base de husk | [mitos.run/docs/mcp](https://mitos.run/docs/mcp) |
| Errores legibles por LLM | Cada fallo lleva `{code, cause, remediation}`, analizado por los SDK en un `AgentRunError` estructurado | [docs/api/errors.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/api/errors.md) |

### Nativo de Kubernetes

| Capacidad | Lo que obtienes | Documentación |
|---|---|---|
| CRDs declarativos | `SandboxPool`, `Sandbox` (fuente poolRef/fromSandbox/fromRevision), `Workspace`/`WorkspaceRevision` en `mitos.run/v1` con topología de volúmenes y comportamiento de fork | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| Ejecución pod-native | Cada VM por sandbox se ejecuta en un pod no privilegiado (`/dev/kvm` de un plugin de dispositivo, no `privileged`), por lo que las solicitudes de CPU/memoria son la verdad del scheduler y PSA gobierna el pod | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Planificación consciente de capacidad | Empaquetado CoW en holders calientes, un presupuesto de sobrecompromiso consciente de CoW, un techo `MaxSandboxes` DoS de host con reserva atómica de slots y contrapresión `NoCapacity` tipificada en lugar de OOM en un nodo | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| Autoescalado impulsado por demanda | `SandboxPool.spec.autoscale` escala el recuento de pods husk inactivos a `clamp(inUse + targetSpare, minWarm, maxWarm)` con un tiempo de espera anti-oscilación; un pool fijo es simplemente `minWarm == replicas` | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| Semántica de fallo y GC | TTLs de reclamación, barrido de VMs huérfanas, reconciliación tras reinicio del controlador, cosecha de fallos de forkd mediante un diario en disco, manejo de pérdida de nodo y contrapresión de saturación, todo probado en CI | [docs/failure-gc.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/failure-gc.md) |

### Estado durable

| Capacidad | Lo que obtienes | Documentación |
|---|---|---|
| Espacios de trabajo durables y bifurcables | CRDs `Workspace`/`WorkspaceRevision`: estado de agente durable, versionado y bifurcable independiente de cualquier sandbox. `/workspace` se hidrata al inicio y una revisión comprometida se deshidrata al terminar a través del almacén direccionado por contenido. Verificado crear -> commit -> fork en un clúster KVM real | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| Salidas y diff | `spec.lifetime.onTerminate.outputs` reduce la deshidratación a los subárboles listados; `{diff: true}` registra un diff de hash de contenido contra la cabeza padre | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| Punto de encuentro Git | Una salida `{git}` empuja ramas por intento a un remoto de encuentro (el motor empuja; un humano o CI fusiona). Mejor esfuerzo en husk hoy | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| URL de entorno de desarrollo | `mitos workspace serve <ws> --pool P` reclama en caliente un sandbox bifurcado vinculado al espacio de trabajo y devuelve una URL `https://<label>.<expose-domain>/` lista; cada sesión bifurcada obtiene su propia URL | [docs/recipes/dev-environment.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/recipes/dev-environment.md) |

### Operable

| Capacidad | Lo que obtienes | Documentación |
|---|---|---|
| Métricas y trazado | Métricas Prometheus de nodo y controlador, un trace OpenTelemetry por reclamación (`--otlp-endpoint`) y un registro de auditoría estructurado conmutable (`--audit-log`) que registra comando/ruta y recuentos de bytes, nunca contenido o secretos | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| Medición consciente de CoW | El conjunto de páginas de plantilla compartidas se cuenta una vez, no una vez por fork, por lo que la facturación y la planificación reflejan la huella física honesta | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| Herramientas de operador | Plugin `kubectl mitos` (`ls` / `ps`) y el informe operativo `GET /v1/metering` | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| Bare metal como ciudadano de primera clase | Talos + Hetzner es la plataforma de referencia | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) |
| Primer arranque para un solo usuario | Inicio rápido k3s con una puerta de inicio de sesión de un usuario (solo QA, no producción) | [docs/platforms/k3s-quickstart.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/k3s-quickstart.md) |

## Comparación

Una tabla de números cara a cara pertenece aquí solo cuando nuestro harness pueda regenerarla contra los competidores reales en el mismo hardware, con scripts en este repositorio. Ese harness es [#15](https://github.com/mitos-run/mitos/issues/15). Las cifras a continuación son **números publicados por otros proveedores, para diferentes operaciones, en diferentes hardware, con diferente metodología**: no han sido medidos por nosotros y no son una afirmación de comparación directa.

| Runtime | Cifra publicada (de ellos, no nuestra) | Operación que describen |
|---|---|---|
| Mitos (nuestra, medida) | ~27 ms P50 | activación warm-claim en el nodo de referencia bare-metal |
| E2B | ~150 ms | creación de sandbox |
| Daytona | sub-90 ms | creación desde snapshot |
| Modal | sub-second | creación de sandbox |
| CodeSandbox SDK | ~863 ms / ~495 ms | fork en vivo / reanudación desde memoria |
| Fly Machines | < 1 s | inicio de máquina |

Lo que es comparable y real hoy es el mapa de Pareto cualitativo: la combinación de código abierto, auto-alojable, nativo de k8s y fork de snapshot en vivo es el eje donde Mitos está solo.

| | Mitos | E2B | Modal | Daytona | Morph | Cloudflare | Box | Agent Sandbox | Kata/KubeVirt | Firecracker puro |
|---|---|---|---|---|---|---|---|---|---|---|
| Aislamiento de hardware por sesión | KVM microVM | microVM | gVisor | contenedor/VM | microVM | aislamiento V8 | VM | opción Kata | KVM | KVM |
| Fork de snapshot de estado en ejecución | sí, primitiva central | snapshot/reanudación | snapshots de memoria | no | sí (Infinibranch) | no | fork de disco | no | no | DIY |
| Reclamaciones en milisegundos desde pool caliente | sí (centro de diseño) | pools calientes | pools calientes | espacios de trabajo | sí | aislamientos instantáneos | no publicado | 1-3s en frío | segundos | DIY |
| Espacios de trabajo durables y bifurcables | CRD Workspace | no | volúmenes | espacios de trabajo | sí, propietario | sí (disco) | no | PVCs | PVCs | no |
| API nativa de Kubernetes | CRDs | API SaaS | API SaaS | SaaS/OSS | API SaaS | API SaaS | CLI nativa de agente | CRDs | CRDs | no |
| Auto-alojable | sí, cualquier clúster KVM | OSS parcial | no | núcleo OSS | no | no | no | sí | sí | sí |
| Opción alojada | planeado (mismo motor) | sí | sí | sí | sí | sí | sí (solo) | no | no | no |
| Tus datos permanecen en tu infraestructura | sí (auto-alojado) | no | no | parcial | no | no | no | sí | sí | sí |
| Código abierto | Apache 2.0 | parcial | no | parcial | no | no | no | Apache 2.0 | Apache 2.0 | Apache 2.0 |

Los runtimes SaaS (E2B, Modal, Daytona, Cloudflare) son rápidos, pero el código, los datos y las credenciales de tus agentes se ejecutan en infraestructura de otra persona sin una ruta de auto-alojamiento con capacidad equivalente. Morph construyó el modelo de estado correcto (rama/restauración) como una nube propietaria; nuestra primitiva Workspace apunta a la misma semántica, de código abierto, a velocidades de fork(2). Agent Sandbox (k8s-sigs) está ganando el estándar de API de Kubernetes sin un motor de fork de snapshot, por lo que enviamos una fachada de conformidad (`cmd/facade`) para ser su backend más rápido en lugar de luchar contra él ([docs/facade-conformance.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/facade-conformance.md)). Kata, KubeVirt y Firecracker puro te dan la primitiva de aislamiento y te dejan las capas de pool, fork, distribución y API de agente como tu problema.

Si una alternativa nos supera en un eje que te importa y no tenemos una línea de hoja de ruta que lo cierre, eso es un error en nuestra estrategia: abre un issue.

## Arquitectura

Mitos arranca microVMs de Firecracker, las bifurca a través de snapshots copy-on-write y expone todo el ciclo de vida a través de CRDs declarativos (`SandboxPool`, `Sandbox`, `Workspace`) en el grupo de API `mitos.run/v1`. Un sandbox es una microVM, no un pod: obtiene aislamiento de hardware a través de KVM, y los mecanismos a nivel de pod (NetworkPolicy, ResourceQuota, PSA) no lo gobiernan.

Las piezas:

- **controller** (Deployment): reconcilia los CRDs, selecciona un nodo y dirige `forkd`. Realiza un seguimiento de los nodos de fork disponibles a través de un registro alimentado por latidos de capacidad por nodo.
- **forkd** (DaemonSet): el daemon por nodo que posee las VMs. Sirve gRPC en `:9090` para el controlador (fork, prepare-pool, heartbeat) y una API HTTP de sandbox en `:9091` para tráfico exec y de archivos. Necesita `/dev/kvm`, por lo que se ejecuta solo en nodos con capacidad KVM.
- **guest agent**: PID 1 dentro de cada microVM. Habla un protocolo vsock para exec, archivos, entorno y notificaciones de fork.
- **sandbox-server**: el mismo motor de fork detrás de una API REST simple, sin necesidad de Kubernetes, para bucles locales y uso en un solo host.
- **SDKs** (`sdk/python`, `sdk/typescript`, `sdk/go` y más): clientes para el servicio alojado, un clúster o `sandbox-server`.

Dos rutas críticas transportan el sistema:

- **Ruta de reclamación**: el controlador elige un nodo caliente del registro y llama a `forkd` `Fork` a través de gRPC; el sandbox resultante informa Ready a través de la API HTTP de `forkd` en ese nodo.
- **Ruta de exec**: el SDK o CLI habla con `forkd` en `:9091`, que puentea a través de vsock al guest agent dentro de la VM.

Fork es la primitiva central: una VM fuente se snapshot una vez y N hijos restauran desde ese snapshot mediante copy-on-write, por lo que cada hermano aterriza caliente e independiente mientras las páginas de plantilla compartidas se almacenan y miden una vez. Debido a que Firecracker necesita virtualización de hardware, bare metal (Talos en Hetzner es la plataforma de referencia) es un objetivo de primera clase; el plano de control en la nube permanece en nodos ordinarios mientras la ejecución aterriza en máquinas con capacidad KVM.

## Estado del proyecto

Desarrollo temprano, pre-1.0 (último lanzamiento `v0.3.0`). No ejecutes código no confiable en producción todavía: no ha habido ninguna revisión de seguridad externa y algunos controles de aislamiento permanecen abiertos (consulta el [modelo de amenazas](https://mitos.run/docs/threat-model) para el estado exacto por límite). El plano de control es real de extremo a extremo, probado en CI contra motores simulados y VMs reales de Firecracker, y ejercitado en un clúster KVM Talos de un solo nodo.

**Verificado en un clúster KVM real (husk predeterminado):** activación warm-claim, exec bloqueante, `run_code` fallando cerrado con `KernelUnavailable`, auto-curación / re-pendiente, calentamiento de pool más autoescalado por demanda, fork de sandbox en vivo (el pod husk fuente hace snapshot de su VM y N pods hijos la restauran mediante CoW, cada uno un hijo Ready independiente), espacios de trabajo durables y bifurcables (crear -> commit -> fork), y aislamiento de egreso de pod (denegación por defecto, bloqueo de metadatos de nube, lista de permitidos por plantilla).

**Colas rastreadas aún no en el husk predeterminado:** exec en streaming y el PTY interactivo; hooks de snapshot de memoria de VM en vivo para cabezas de espacio de trabajo reanudables; selección de almacén en vivo S3/cifrado; el push de workspace `{git}` de husk; y multi-nodo N>1 (diseñado, verificado en un solo nodo).

[ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md) es la fuente única de lo que está hecho, en progreso y bloqueado. La regla operativa: este repositorio nunca describe un sistema que no existe.

## Desarrollo local (no se requiere KVM)

`mitos dev up` levanta un clúster kind local en un plano de control simulado y el CLI `mitos` impulsa la ruta de reclamación completa; el motor simulado reconcilia las reclamaciones a Ready y ejercita el despacho del plano de control, pero un `exec` real dentro de la VM necesita un nodo con `/dev/kvm`. Para el bucle REST sin clúster, ejecuta `go run ./cmd/sandbox-server --mock --addr :8080` y apunta el SDK de Python hacia él. El tutorial completo de kind está en [mitos.run/docs/cli](https://mitos.run/docs/cli).

## Documentación

La documentación completa reside en **[mitos.run/docs](https://mitos.run/docs)**: inicio rápido, arquitectura, referencia de SDK y CLI, ciclo de vida del sandbox, espacios de trabajo, redes y el modelo de amenazas, todo renderizado desde este repositorio.

La larga cola completa (plantillas, formato y distribución de snapshot, cifrado y secretos, planificación y densidad, fallo y GC, corrección del motor de fork, recetas y la especificación de la API v2 objetivo) reside en [`docs/`](https://github.com/mitos-run/mitos/blob/HEAD/docs/) en este repositorio. La metodología de benchmarks está en [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md).

## Contribuciones

Las contribuciones son bienvenidas. Consulta [CONTRIBUTING.md](https://github.com/mitos-run/mitos/blob/HEAD/CONTRIBUTING.md) y [CLAUDE.md](https://github.com/mitos-run/mitos/blob/HEAD/CLAUDE.md) para las convenciones, y la [página de issues](https://github.com/mitos-run/mitos/issues) para el trabajo rastreado contra [ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md).

## Seguridad

El modelo de amenazas con estado por límite reside en [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model); aún no se ha realizado ninguna revisión de seguridad externa, y el documento dice exactamente lo que está abierto. Para reportar una vulnerabilidad, consulta [SECURITY.md](https://github.com/mitos-run/mitos/blob/HEAD/SECURITY.md).

## Licencia

[Apache 2.0](https://github.com/mitos-run/mitos/blob/HEAD/LICENSE).