O SDK usa por padrão o endpoint hospedado. O mesmo código é executado contra o seu próprio cluster ou um sandbox-server autônomo, definindo `MITOS_BASE_URL`. A chave é resolvida a partir do argumento ou de `MITOS_API_KEY` e nunca é registrada.

### 2. Crie um sandbox e execute 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

O cliente assíncrono espelha a mesma superfície: `await mitos.aio.create("python")` retorna um `AsyncDirectSandbox` com os mesmos `exec` / `run_code` / `files` / `create_pty` / `fork` / `terminate`.

Os `exec` e `run_code` bloqueantes funcionam no husk padrão. O exec em streaming (`sb.exec(..., on_stdout=...)`), processos em segundo plano (`sb.exec_background(...)`) e o PTY interativo (`sb.create_pty()`) rodam no caminho do engine hoje e estão sendo trazidos para o husk padrão; `run_code` retorna um `KernelUnavailable` fail-closed até que o kernel seja incluído na imagem base do husk.

### Execute do seu jeito

Mesmo engine, mesma API, mais pontos de entrada. Aprofundar é um clique na [documentação](https://mitos.run/docs).

**Cada linguagem, dois modos.** Cada SDK fala a mesma API REST do sandbox-server no **modo direto** (standalone ou hospedado), e cada um também tem o **modo cluster** (um `AgentRun` que controla os CRDs `mitos.run/v1` por meio da API do Kubernetes). A nomenclatura do pool padrão é idêntica byte a byte nos seis.

| Linguagem | Instalação | Direto | Cluster | Docs do SDK |
|---|---|---|---|---|
| Python | `pip install mitos-run` | sync + async | `AgentRun` | [sdk/python](https://github.com/mitos-run/mitos/blob/HEAD/sdk/python) |
| TypeScript | `npm i @mitos/sdk` | sim | `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, compatível com `errors.Is` | `AgentRun` | [sdk/go](https://github.com/mitos-run/mitos/blob/HEAD/sdk/go/README.md) |
| Ruby | gem (apenas stdlib) | sim | `AgentRun` | [sdk/ruby](https://github.com/mitos-run/mitos/blob/HEAD/sdk/ruby/README.md) |
| Rust | crate (bloqueante) | sim | `AgentRun` | [sdk/rust](https://github.com/mitos-run/mitos/blob/HEAD/sdk/rust/README.md) |
| Java | JDK 17 (apenas stdlib) | sim | `AgentRun` | [sdk/java](https://github.com/mitos-run/mitos/blob/HEAD/sdk/java/README.md) |

O SDK Go é distribuído em seu próprio módulo aninhado (`github.com/mitos-run/mitos/sdk/go`), então importá-lo nunca puxa o controller para o seu build.

**Self-hosting? Mesmo código.** O Helm chart implanta o mesmo gateway que o serviço hospedado executa, então o quickstart acima funciona sem alterações contra o seu próprio cluster: aponte `MITOS_BASE_URL` para o seu gateway e mantenha todo o resto. Hospedado e self-hosted são uma única experiência; apenas a URL e quem o opera diferem.

**Controle nativo do Kubernetes, quando você quiser.** Para times de plataforma que gerenciam pools de forma declarativa (GitOps, automação com escopo RBAC, operadores), o caminho `AgentRun` de dois níveis contorna o gateway e controla os CRDs `mitos.run/v1` diretamente pela API do 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` traz um plano de controle local de comando único em um mecanismo simulado para
desenvolvimento em modo cluster. Um servidor MCP (`mitos-mcp`) expõe sandboxes como
ferramentas MCP para qualquer agente que fale MCP, e uma [Skill de Agente](https://github.com/mitos-run/mitos/blob/HEAD/skills/mitos/SKILL.md)
ensina o fluxo de trabalho a agentes com suporte a skills. A matriz completa de instalação (script,
Homebrew, deb/rpm, scoop/winget, checksums) está em
[mitos.run/docs/install](https://mitos.run/docs/install).

**Integre-se ao agente que você já usa.** Cada adaptador é uma camada fina sobre as mesmas operações nativas (`exec`, `run_code`, `files`, `fork`), sem dependência rígida do pacote do framework: Claude Code e opencode (servidor MCP + skill de agente), o OpenAI Agents SDK, o Claude Agent SDK, LangChain / deepagents, Vercel AI SDK / Pydantic AI / AutoGen / LlamaIndex (MCP padrão), e shims de migração do tipo "mude uma importação" para equipes que estão deixando as nuvens [E2B](https://mitos.run/docs/migrating-from-e2b) ou [Daytona](https://mitos.run/docs/migrating-from-daytona). O [hub de integrações](https://github.com/mitos-run/mitos/blob/HEAD/docs/integrations/README.md) indexa todos os caminhos.

**Instale o operador.**```bash
kubectl apply -k deploy/

**Onde é executado.** O único requisito do nó é `/dev/kvm` mais o rótulo `mitos.run/kvm=true`, então o mitos instala em qualquer cluster Kubernetes com nós KVM de metal nu ou virtualização aninhada:

| plataforma | nó KVM | guia |
|---|---|---|
| Metal nu (Talos, Hetzner) | `/dev/kvm` nativo | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) (referência de primeira classe) |
| AWS / EKS | `*.metal` ou grupos de nós com virtualização aninhada | chart genérico hoje; o guia por nuvem é a issue [#919](https://github.com/mitos-run/mitos/issues/919) |
| GKE | pools de nós com virtualização aninhada | chart genérico hoje; o guia por nuvem é a [#919](https://github.com/mitos-run/mitos/issues/919) |
| Azure / AKS | tamanhos de VM compatíveis com virtualização aninhada | chart genérico hoje; o guia por nuvem é a [#919](https://github.com/mitos-run/mitos/issues/919) |

O chart e as CRDs são idênticos em todos eles; apenas o pool de nós que fornece `/dev/kvm` difere.

## Por que Mitos

Os harnesses de agentes precisam de ambientes rápidos e isolados onde os agentes leiam e escrevam arquivos, instalem pacotes e executem código não confiável. Toda opção existente impõe um trade-off: velocidade sem propriedade, isolamento sem fork, nativo do Kubernetes sem inicializações quentes, ou durabilidade presa na nuvem de outra pessoa.

- **Live-fork de uma VM em execução.** Fork copy-on-write de N vias de uma microVM ativa: as filhas compartilham as páginas de memória da mãe até escreverem, então cada fork chega a um ambiente quente e pronto. Ramifique um agente em muitas tentativas paralelas.
- **Ativação warm-claim em ~27 ms.** As microVMs Firecracker restauram a partir de um snapshot de memória na classe das dezenas de milissegundos: P50 ~27 ms no nó de referência de metal nu, reproduzível a partir de [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh).
- **Open source, auto-hospedável, nativo do Kubernetes.** Pelo que sabemos, o único runtime que faz as três coisas. Você conduz todo o ciclo de vida por meio de CRDs declarativas (`mitos.run`).

Duas maneiras de executá-lo:

- **Self-hosted (hoje):** qualquer cluster Kubernetes com nós KVM. Seus dados nunca saem da sua infraestrutura. Metal nu (Talos + Hetzner) é a plataforma de referência de primeira classe.
- **Hospedado (em andamento):** o mesmo mecanismo e API operados por nós, para equipes que querem milissegundos sem gerenciar nós.

> Existem dois caminhos de mecanismo. O **caminho nativo de pod do husk é o padrão**: cada VM é executada em seu próprio pod sem privilégios, e o pod husk de origem captura um snapshot de sua VM em execução para que N pods filhos a restaurem via CoW. O **caminho raw-forkd** executa forks no mecanismo em processo do forkd. Tudo aqui é executado no padrão husk, a menos que seja explicitamente marcado como `engine path`.

Sandboxes não são pods. Mecanismos do Kubernetes com escopo de pod (NetworkPolicy, ResourceQuota, PSA) regem o pod husk, não a carga de trabalho dentro da microVM; o sandbox é a VM, não o pod husk, e onde fornecemos um equivalente, ele é documentado como nosso. Os caminhos completos de dados de claim e exec e o diagrama de componentes estão em [mitos.run/docs/architecture](https://mitos.run/docs/architecture).

## Benchmarks

Cada número aqui é reproduzível a partir de [`bench/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/) em hardware KVM real; nada é publicado sem que o leitor possa regenerar (a regra do projeto de não haver alegações não verificadas). Cada linha nomeia o que mede e o comando exato que o reproduz. Os dados completos por execução e o contexto de hardware estão em [`bench/results/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/).

### Tempo hospedado até a interatividade, contra o conjunto de pares do ComputeSDK

O tempo até a interatividade (TTI) é a única métrica comparável diretamente com o [benchmark público do ComputeSDK](https://github.com/computesdk/benchmarks) contra o qual todo fornecedor de sandbox hospedado é medido: o relógio começa em `create()` e para quando um comando realmente é EXECUTADO dentro do sandbox e retorna.

| fornecedor | TTI P50 | medição |
|---|---|---|
| northflank | 95.9 ms | publicado pelo ComputeSDK |
| **mitos** | **96.8 ms** | nosso harness, `api.mitos.run` |
| daytona | 136.2 ms | publicado pelo ComputeSDK |
| e2b | 365.6 ms | publicado pelo ComputeSDK |

Reproduza nosso número e a tabela de pares (os números dos pares são lidos do commit imutável publicado pelo ComputeSDK, não re-executados por nós):```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

Full method and hardware in [bench/README.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/README.md); results in [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) and [2026-06-21-kvm-perf-correctness.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/2026-06-21-kvm-perf-correctness.md).

### Ativação warm-claim (o mecanismo, não o percurso de ida e volta)

A ativação warm-sandbox do próprio mecanismo (carregamento de snapshot + handshake de correção de fork + guest-ready) é P50 ~27 ms no nó de referência bare-metal, reproduzível a partir de [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh). Este é um número menor e diferente do que o TTI hospedado de ponta a ponta acima; citar o número do mecanismo contra o número de create-API de um concorrente seria um erro de categoria, então os mantemos separados.

## Recursos

O caminho pod-nativo husk é o padrão. Alguns recursos são executados hoje apenas no raw-forkd `engine path` e estão marcados, com um link para a issue de rastreamento.

### Velocidade

| Recurso | O que você obtém | Documentação |
|---|---|---|
| Ativação warm-claim | P50 ~27 ms no nó de referência bare-metal (carregamento de snapshot + handshake de correção de fork + guest-ready); ~6-16 ms de restauração de snapshot; ~3 MiB de memória marginal por fork via compartilhamento de páginas CoW | [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md) |
| Pools pré-snapshot | Imagens OCI achatadas em ext4 rootfs e aquecidas com suas etapas `init` antes do snapshot, para que não haja cold start no claim | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| Compartilhamento de memória CoW | Você paga pelas páginas exclusivas entre forks, não por cópias | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| Distribuição endereçada por conteúdo | Forks puxam apenas os chunks sha256 ausentes de um detentor via mTLS; rebuilds enviam deltas sob um contrato de compatibilidade de versão | [docs/snapshot-distribution.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/snapshot-distribution.md) |

### Isolamento

| Recurso | O que você obtém | Documentação |
|---|---|---|
| Isolamento de hardware por sessão | Um kernel dedicado por sandbox (KVM/Firecracker); no padrão husk, cada VM executa em seu próprio pod não privilegiado e restrito por PSA, que é a fronteira por VM | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Sem herança silenciosa de segredos | Forks ao vivo de sandboxes que contêm segredos são rejeitados, a menos que haja adesão explícita; as credenciais são injetadas no momento do claim via vsock, nunca embutidas nos snapshots | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Egress com negação por padrão | Um filtro nftables default-deny dentro do pod, na própria netns do pod (independente de CNI), com bloqueio incondicional de cloud-metadata (169.254.169.254) e uma allowlist por template por IP:porta e por nome por meio de um proxy DNS dentro do pod. Verificado de ponta a ponta em um cluster KVM real; o guest não pode influenciar a aplicação | [mitos.run/docs/networking](https://mitos.run/docs/networking) |
| Criptografia em repouso | Contêineres LUKS2 por escopo com crypto-shredding e encapsulamento de envelope KMS (atrás de `--enable-encryption`, fail-closed); chaves respaldadas por HSM e escopo por workspace são acompanhamentos futuros | [docs/encryption.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/encryption.md) |

### DX para agentes

| Recurso | O que você obtém | Documentação |
|---|---|---|
| Exec bloqueante | stdout e código de saída corretos por meio da API de sandbox | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| Exec com streaming e PTY | stdout/stderr incremental, processos em segundo plano e um terminal WebSocket interativo com gate de token (`engine path`) | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| Interpretador de código | `run_code` com um kernel stateful e resultados ricos em multi-MIME, em todos os SDKs e no servidor MCP; `KernelUnavailable` fail-closed até o kernel ser incluído na imagem base husk | [mitos.run/docs/mcp](https://mitos.run/docs/mcp) |
| Erros legíveis por LLM | Cada falha carrega `{code, cause, remediation}`, parseado pelos SDKs em um `AgentRunError` estruturado | [docs/api/errors.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/api/errors.md) |

### Nativo do Kubernetes

| Recurso | O que você obtém | Documentação |
|---|---|---|
| CRDs declarativos | `SandboxPool`, `Sandbox` (fonte poolRef/fromSandbox/fromRevision), `Workspace`/`WorkspaceRevision` em `mitos.run/v1` com topologia de volume e comportamento de fork | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| Execução pod-nativa | Cada VM por sandbox executa em um pod não privilegiado (`/dev/kvm` de um device plugin, não `privileged`), então as requests de CPU/memória são a fonte de verdade do agendador e a PSA governa o pod | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Agendamento ciente de capacidade | CoW bin-packing em detentores aquecidos, um orçamento de overcommit ciente de CoW, um teto de host-DoS `MaxSandboxes` com reserva atômica de slots e backpressure tipado `NoCapacity` em vez de causar OOM em um nó | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| Autoscaling orientado por demanda | `SandboxPool.spec.autoscale` dimensiona a contagem de husk-pods dormentes para `clamp(inUse + targetSpare, minWarm, maxWarm)` com um cooldown anti-thrash; um pool fixo é apenas `minWarm == replicas` | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| Semânticas de falha e GC | TTLs de claim, varreduras de VMs órfãs, reconciliação após reinício do controller, recolhimento de crashes do forkd via journal em disco, tratamento de perda de nó e backpressure de saturação, tudo comprovado em CI | [docs/failure-gc.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/failure-gc.md) |

### Estado durável

| Recurso | O que você obtém | Documentação |
|---|---|---|
| Workspaces duráveis e forkáveis | CRDs `Workspace`/`WorkspaceRevision`: estado de agente durável, versionado e forkável, independente de qualquer sandbox. `/workspace` é hidratado na inicialização e uma revisão confirmada é desidratada no encerramento por meio do store endereçado por conteúdo. Verificado create -> commit -> fork em um cluster KVM real | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| Saídas e diff | `spec.lifetime.onTerminate.outputs` restringe a desidratação às subárvores listadas; `{diff: true}` registra um diff de content-hash contra o head pai | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| Rendez-vous Git | Uma saída `{git}` envia branches por tentativa para um remote de rendez-vous (o mecanismo faz o push; um humano ou CI faz o merge). Best-effort no husk hoje | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| URL de ambiente de desenvolvimento | `mitos workspace serve <ws> --pool P` faz warm-claim de um sandbox forkado vinculado ao workspace e retorna uma URL pronta `https://<label>.<expose-domain>/`; cada sessão forkada recebe sua própria URL | [docs/recipes/dev-environment.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/recipes/dev-environment.md) |

### Operabilidade

| Recurso | O que você obtém | Documentação |
|---|---|---|
| Métricas e tracing | Métricas Prometheus de nó e controller, um trace OpenTelemetry por claim (`--otlp-endpoint`) e um log de auditoria estruturado e alternável (`--audit-log`) registrando comando/caminho e contagens de bytes, nunca conteúdo ou segredos | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| Medição ciente de CoW | O conjunto de páginas de template compartilhado é contado uma vez, não uma vez por fork, para que cobrança e agendamento reflitam a pegada física real | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| Ferramentas para operadores | plugin `kubectl mitos` (`ls` / `ps`) e o relatório operacional `GET /v1/metering` | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| Bare metal de primeira classe | Talos + Hetzner é a plataforma de referência | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) |
| Primeira execução para usuário único | quickstart k3s com um gate de login de um usuário (somente QA, não produção) | [docs/platforms/k3s-quickstart.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/k3s-quickstart.md) |

## Comparação

Uma tabela de números frente a frente pertence aqui somente quando nosso harness puder regenerá-la contra os concorrentes reais no mesmo hardware, com scripts neste repositório. Esse harness é o [#15](https://github.com/mitos-run/mitos/issues/15). Os números abaixo são **números publicados por outros fornecedores, para operações diferentes, em hardware diferente, com metodologia diferente**: não foram medidos por nós e não são uma afirmação frente a frente.

| Runtime | Número publicado (deles, não nosso) | Operação que descrevem |
|---|---|---|
| Mitos (nosso, medido) | ~27 ms P50 | ativação warm-claim no nó de referência bare-metal |
| E2B | ~150 ms | criação de sandbox |
| Daytona | sub-90 ms | criação a partir de snapshot |
| Modal | sub-segundo | criação de sandbox |
| CodeSandbox SDK | ~863 ms / ~495 ms | fork ao vivo / memory-resume |
| Fly Machines | < 1 s | inicialização de máquina |

O que é comparável e real hoje é o mapa de pareto qualitativo: a combinação de código aberto, auto-hospedável, nativo do k8s e fork de snapshot ao vivo é o eixo em que a Mitos está sozinha.

| | Mitos | E2B | Modal | Daytona | Morph | Cloudflare | Box | Agent Sandbox | Kata/KubeVirt | raw Firecracker |
|---|---|---|---|---|---|---|---|---|---|---|
| Isolamento de hardware por sessão | KVM microVM | microVM | gVisor | contêiner/VM | microVM | V8 isolate | VM | opção Kata | KVM | KVM |
| Fork de snapshot do estado em execução | sim, primitiva central | snapshot/resume | snapshots de memória | não | sim (Infinibranch) | não | fork de disco | não | não | DIY |
| Claims de milissegundos com warm-pool | sim (centro do design) | warm pools | warm pools | workspaces | sim | isolates instantâneos | não publicado | 1-3s a frio | segundos | DIY |
| Workspaces duráveis e forkáveis | CRD Workspace | não | volumes | workspaces | sim, proprietário | sim (disco) | não | PVCs | PVCs | não |
| API nativa do Kubernetes | CRDs | API SaaS | API SaaS | SaaS/OSS | API SaaS | API SaaS | CLI nativa de agente | CRDs | CRDs | não |
| Auto-hospedável | sim, qualquer cluster KVM | OSS parcial | não | núcleo OSS | não | não | não | sim | sim | sim |
| Opção hospedada | planejada (mesmo mecanismo) | sim | sim | sim | sim | sim | sim (somente) | não | não | não |
| Seus dados permanecem na sua infra | sim (auto-hospedado) | não | não | parcial | não | não | não | sim | sim | sim |
| Código aberto | Apache 2.0 | parcial | não | parcial | não | não | não | Apache 2.0 | Apache 2.0 | Apache 2.0 |

Os runtimes SaaS (E2B, Modal, Daytona, Cloudflare) são rápidos, mas o código, os dados e as credenciais dos seus agentes são executados na infraestrutura de outra pessoa, sem um caminho de auto-hospedagem com capacidade equivalente. A Morph construiu o modelo de estado certo (branch/restore) como nuvem proprietária; nossa primitiva Workspace tem como alvo a mesma semântica, em código aberto, nas velocidades do fork(2). O Agent Sandbox (k8s-sigs) está vencendo o padrão de API do Kubernetes sem um mecanismo de snapshot-fork, e é por isso que entregamos uma facade de conformidade (`cmd/facade`) para ser o backend mais rápido dele em vez de enfrentá-lo ([docs/facade-conformance.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/facade-conformance.md)). Kata, KubeVirt e Firecracker puro fornecem a primitiva de isolamento e deixam as camadas de pool, fork, distribuição e API de agente como problema seu.

Se uma alternativa nos superar em um eixo que você considera importante e não tivermos nenhuma linha de roadmap que resolva isso, isso é um bug em nossa estratégia: abra uma issue.

## Arquitetura

A Mitos inicializa microVMs Firecracker, faz fork delas por meio de snapshots copy-on-write e expõe todo o ciclo de vida por meio de CRDs declarativos (`SandboxPool`, `Sandbox`, `Workspace`) no grupo de API `mitos.run/v1`. Um sandbox é uma microVM, não um pod: ele recebe isolamento de hardware por meio do KVM, e os mecanismos com escopo de pod (NetworkPolicy, ResourceQuota, PSA) não o governam.

Os componentes:

- **controller** (Deployment): reconcilia os CRDs, seleciona um nó e controla o `forkd`. Ele rastreia os nós de fork disponíveis por meio de um registry alimentado por heartbeats de capacidade por nó.
- **forkd** (DaemonSet): o daemon por nó que possui as VMs. Ele serve gRPC em `:9090` para o controller (fork, prepare-pool, heartbeat) e uma API HTTP de sandbox em `:9091` para tráfego de exec e arquivos. Ele precisa de `/dev/kvm`, portanto executa apenas em nós com capacidade KVM.
- **guest agent**: PID 1 dentro de cada microVM. Ele fala um protocolo vsock para exec, arquivos, ambiente e notificações de fork.
- **sandbox-server**: o mesmo mecanismo de fork por trás de uma API REST simples, sem exigir Kubernetes, para loops locais e uso em host único.
- **SDKs** (`sdk/python`, `sdk/typescript`, `sdk/go` e outros): clientes para o serviço hospedado, um cluster ou o `sandbox-server`.

Dois hot paths sustentam o sistema:

- **Claim path**: o controller escolhe um nó aquecido do registry e chama `Fork` do `forkd` via gRPC; o sandbox resultante reporta Ready por meio da API HTTP do `forkd` naquele nó.
- **Exec path**: o SDK ou a CLI fala com o `forkd` em `:9091`, que faz a ponte via vsock para o guest agent dentro da VM.

O fork é a primitiva central: uma VM de origem é snapshotada uma vez e N filhos restauram a partir desse snapshot via copy-on-write, de modo que cada irmão chega aquecido e independente, enquanto as páginas de template compartilhadas são armazenadas e medidas uma única vez. Como o Firecracker precisa de virtualização por hardware, o bare metal (Talos na Hetzner é a plataforma de referência) é um alvo de primeira classe; o control plane em nuvem permanece em nós comuns enquanto a execução ocorre em máquinas com capacidade KVM.

## Status do projeto

Desenvolvimento inicial, pré-1.0 (última versão `v0.3.0`). Ainda não execute código não confiável em produção: não houve revisão de segurança externa e alguns controles de isolamento permanecem em aberto (consulte o [modelo de ameaças](https://mitos.run/docs/threat-model) para o status exato por fronteira). O control plane é real de ponta a ponta, comprovado em CI contra mecanismos mock e VMs Firecracker reais, e exercitado em um cluster Talos KVM de nó único.

**Verificado em um cluster KVM real (padrão husk):** ativação warm-claim, exec bloqueante, `run_code` com falha fail-closed (`KernelUnavailable`), auto-cura / re-pend, aquecimento de pool mais autoscaling por demanda, fork de sandbox ao vivo (o husk pod de origem captura um snapshot da sua VM e N pods filhos a restauram via CoW, cada um um filho Ready independente), workspaces duráveis e forkáveis (create -> commit -> fork) e isolamento de egress do pod (default-deny, bloqueio de cloud-metadata, allowlist por template).

**Pendências rastreadas ainda fora do padrão husk:** exec com streaming e o PTY interativo; hooks de snapshot de memória de VM ao vivo para heads de workspace retomáveis; seleção dinâmica de store com S3/criptografia; o push de workspace `{git}` do husk; e multi-nó N>1 (projetado, verificado em nó único).

[ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md) é a fonte única do que está pronto, em andamento e bloqueado. A regra operacional: este repositório nunca descreve um sistema que não existe.

## Desenvolvimento local (sem exigir KVM)

`mitos dev up` sobe um cluster kind local em um control plane mock e a CLI `mitos` conduz todo o caminho de claim; o mecanismo mock reconcilia claims para `Ready` e exercita o dispatch do control plane, mas um `exec` real dentro da VM precisa de um nó com `/dev/kvm`. Para o loop REST sem cluster, execute `go run ./cmd/sandbox-server --mock --addr :8080` e aponte o SDK Python para ele. O walkthrough completo do kind está em [mitos.run/docs/cli](https://mitos.run/docs/cli).

## Documentação

A documentação completa está em **[mitos.run/docs](https://mitos.run/docs)**: quickstart, arquitetura, referência de SDK e CLI, ciclo de vida do sandbox, workspaces, rede e o modelo de ameaças, tudo renderizado a partir deste repositório.

A cauda longa completa (templates, formato e distribuição de snapshots, criptografia e segredos, agendamento e densidade, falha e GC, correção do mecanismo de fork, receitas e a especificação da API v2 alvo) está em [`docs/`](https://github.com/mitos-run/mitos/blob/HEAD/docs/) neste repositório. A metodologia de benchmarks está em [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md).

## Contribuindo

Contribuições são bem-vindas. Consulte [CONTRIBUTING.md](https://github.com/mitos-run/mitos/blob/HEAD/CONTRIBUTING.md) e [CLAUDE.md](https://github.com/mitos-run/mitos/blob/HEAD/CLAUDE.md) para as convenções e a [página de issues](https://github.com/mitos-run/mitos/issues) para o trabalho acompanhado em relação ao [ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md).

## Segurança

O modelo de ameaças com status por fronteira está em [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model); nenhuma revisão de segurança externa aconteceu ainda, e o documento diz exatamente o que está em aberto. Para relatar uma vulnerabilidade, consulte [SECURITY.md](https://github.com/mitos-run/mitos/blob/HEAD/SECURITY.md).

## Licença

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