### 2. 샌드박스를 만들고 코드 실행하기

SDK는 기본적으로 호스팅된 엔드포인트를 사용합니다. 동일한 코드가 `MITOS_BASE_URL`을 설정하여 자체 클러스터나 독립형 샌드박스 서버에서도 실행됩니다. 키는 인수 또는 `MITOS_API_KEY`에서 확인되며 절대 로깅되지 않습니다.```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

비동기 클라이언트도 동일한 인터페이스를 제공합니다: `await mitos.aio.create("python")`은 `AsyncDirectSandbox`를 반환하며, 동일한 `exec` / `run_code` / `files` / `create_pty` / `fork` / `terminate` 기능을 갖습니다.

블로킹 `exec`와 `run_code`는 기본 husk에서 작동합니다. 스트리밍 exec (`sb.exec(..., on_stdout=...)`), 백그라운드 프로세스 (`sb.exec_background(...)`), 그리고 대화형 PTY (`sb.create_pty()`)는 현재 엔진 경로에서 실행되며, 기본 husk로 이전되고 있습니다; `run_code`는 husk 기본 이미지에 커널이 포함될 때까지 실패-폐쇄 방식의 `KernelUnavailable`을 반환합니다.

### 원하는 방식으로 실행하세요

동일한 엔진, 동일한 API, 더 많은 진입점. 자세한 내용은 [문서](https://mitos.run/docs)를 한 번 클릭하세요.

**모든 언어, 두 가지 모드.** 각 SDK는 **직접 모드**(독립 실행형 또는 호스팅)에서 동일한 샌드박스 서버 REST API를 사용하며, 각각 **클러스터 모드**(Kubernetes API를 통해 `mitos.run/v1` CRD를 구동하는 `AgentRun`)도 있습니다. 기본 풀 이름은 여섯 가지 SDK 모두에서 바이트 단위로 동일합니다.

| 언어 | 설치 | 직접 | 클러스터 | 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` | yes | `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` | typed, `errors.Is`-friendly | `AgentRun` | [sdk/go](https://github.com/mitos-run/mitos/blob/HEAD/sdk/go/README.md) |
| Ruby | gem (stdlib only) | yes | `AgentRun` | [sdk/ruby](https://github.com/mitos-run/mitos/blob/HEAD/sdk/ruby/README.md) |
| Rust | crate (blocking) | yes | `AgentRun` | [sdk/rust](https://github.com/mitos-run/mitos/blob/HEAD/sdk/rust/README.md) |
| Java | JDK 17 (stdlib only) | yes | `AgentRun` | [sdk/java](https://github.com/mitos-run/mitos/blob/HEAD/sdk/java/README.md) |

Go SDK는 자체 중첩 모듈(`github.com/mitos-run/mitos/sdk/go`)로 제공되므로, 이를 임포트해도 컨트롤러가 빌드에 포함되지 않습니다.

**셀프 호스팅? 동일한 코드.** Helm 차트는 호스팅 서비스가 실행하는 동일한 게이트웨이를 배포하므로, 위의 빠른 시작은 자체 클러스터에서도 변경 없이 작동합니다: `MITOS_BASE_URL`을 게이트웨이로 지정하고 나머지는 그대로 유지하세요. 호스팅과 셀프 호스팅은 하나의 경험입니다; URL과 운영 주체만 다릅니다.

**원할 때 Kubernetes 네이티브 제어.** 풀을 선언적으로 관리하는 플랫폼 팀(GitOps, RBAC 범위 자동화, 운영자)을 위해, 2계층 `AgentRun` 경로는 게이트웨이를 건너뛰고 Kubernetes API를 통해 `mitos.run/v1` CRD를 직접 구동합니다:```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`는 클러스터 모드 개발을 위한 모의 엔진에서 원커맨드 로컬 제어 플레인을 구동합니다. MCP 서버(`mitos-mcp`)는 MCP를 지원하는 모든 에이전트에게 샌드박스를 MCP 도구로 제공하며, [Agent Skill](https://github.com/mitos-run/mitos/blob/HEAD/skills/mitos/SKILL.md)은 스킬 인식 에이전트에게 워크플로를 가르칩니다. 전체 설치 매트릭스(스크립트, Homebrew, deb/rpm, scoop/winget, 체크섬)는 [mitos.run/docs/install](https://mitos.run/docs/install)에 있습니다.

**이미 사용 중인 에이전트로 바로 연결하세요.** 각 어댑터는 동일한 네이티브 ops(`exec`, `run_code`, `files`, `fork`) 위의 얇은 심(shim)이며, 프레임워크 패키지에 대한 하드 의존성이 없습니다: Claude Code와 opencode(MCP 서버 + 에이전트 스킬), OpenAI Agents SDK, Claude Agent SDK, LangChain / deepagents, Vercel AI SDK / Pydantic AI / AutoGen / LlamaIndex(표준 MCP), 그리고 [E2B](https://mitos.run/docs/migrating-from-e2b) 또는 [Daytona](https://mitos.run/docs/migrating-from-daytona) 클라우드를 떠나는 팀을 위한 "import 하나 변경" 마이그레이션 심(shim). [통합 허브](https://github.com/mitos-run/mitos/blob/HEAD/docs/integrations/README.md)는 모든 경로를 색인합니다.

**운영자를 설치하세요.**```bash
kubectl apply -k deploy/

**실행 환경.** 유일한 노드 요구 사항은 `/dev/kvm`과 `mitos.run/kvm=true` 레이블입니다. 따라서 mitos는 베어메탈 또는 중첩 가상화 KVM 노드가 있는 모든 Kubernetes 클러스터에 설치됩니다:

| 플랫폼 | KVM 노드 | 가이드 |
|---|---|---|
| 베어 메탈 (Talos, Hetzner) | 네이티브 `/dev/kvm` | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) (1차 참조) |
| AWS / EKS | `*.metal` 또는 중첩 가상화 노드 그룹 | 현재 일반 차트; 클라우드별 가이드는 이슈 [#919](https://github.com/mitos-run/mitos/issues/919) 참조 |
| GKE | 중첩 가상화 노드 풀 | 현재 일반 차트; 클라우드별 가이드는 [#919](https://github.com/mitos-run/mitos/issues/919) 참조 |
| Azure / AKS | 중첩 가상화 가능 VM 크기 | 현재 일반 차트; 클라우드별 가이드는 [#919](https://github.com/mitos-run/mitos/issues/919) 참조 |

차트와 CRD는 모두 동일합니다. 유일한 차이는 `/dev/kvm`을 제공하는 노드 풀입니다.

## Mitos를 선택해야 하는 이유

에이전트 하네스는 에이전트가 파일을 읽고 쓰고, 패키지를 설치하고, 신뢰할 수 없는 코드를 실행할 수 있는 빠르고 격리된 환경이 필요합니다. 기존의 모든 옵션은 트레이드오프를 강제합니다: 소유권 없이 속도, 포크 없이 격리, 웜 스타트 없이 Kubernetes 네이티브, 또는 타사 클라우드에 고정된 내구성 중 하나를 선택해야 합니다.

- **실행 중인 VM을 라이브 포크합니다.** 실행 중인 마이크로VM의 N-방향 COW(copy-on-write) 포크: 자식은 쓰기 작업을 수행할 때까지 부모의 메모리 페이지를 공유하므로 각 포크는 미리 준비된 웜 환경에서 시작됩니다. 하나의 에이전트를 여러 병렬 시도로 분기시킵니다.
- **~27 ms 웜 클레임 활성화.** Firecracker 마이크로VM은 수십 밀리초 단위로 메모리 스냅샷에서 복원됩니다: 베어메탈 참조 노드에서 P50 ~27 ms, [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh)에서 재현 가능합니다.
- **오픈 소스, 자체 호스팅 가능, Kubernetes 네이티브.** 우리가 아는 한, 세 가지를 모두 제공하는 유일한 런타임입니다. 선언적 CRD(`mitos.run`)를 통해 전체 수명 주기를 관리합니다.

두 가지 실행 방법:

- **자체 호스팅 (현재):** KVM 노드가 있는 모든 Kubernetes 클러스터. 데이터가 인프라를 벗어나지 않습니다. 베어 메탈 (Talos + Hetzner)이 1차 참조 플랫폼입니다.
- **호스팅 (진행 중):** 노드를 관리하지 않고 밀리초 단위를 원하는 팀을 위해 동일한 엔진과 API를 운영자가 제공합니다.

> 두 가지 엔진 경로가 있습니다. **허스크 팟 네이티브 경로가 기본값입니다:** 각 VM은 자체 권한 없는 팟에서 실행되며, 소스 허스크 팟은 실행 중인 VM을 스냅샷하여 N개의 자식 팟이 COW를 통해 복원합니다. **raw-forkd 경로**는 forkd의 인프로세스 엔진에서 포크를 실행합니다. 여기서 모든 내용은 명시적으로 `engine path`로 표시되지 않는 한 허스크 기본값을 기준으로 합니다.

샌드박스는 팟이 아닙니다. 팟 범위의 Kubernetes 메커니즘(NetworkPolicy, ResourceQuota, PSA)은 마이크로VM 내부의 워크로드가 아닌 허스크 팟을 제어합니다. 샌드박스는 VM이며, 허스크 팟이 아닙니다. 동등한 기능을 제공하는 경우 당사의 문서로 기록됩니다. 전체 클레임 및 exec 데이터 경로와 컴포넌트 다이어그램은 [mitos.run/docs/architecture](https://mitos.run/docs/architecture)에서 확인할 수 있습니다.

## 벤치마크

여기에 나온 모든 수치는 실제 KVM 하드웨어에서 [`bench/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/)를 사용하여 재현 가능합니다. 독자가 직접 재현할 수 없는 데이터는 게시되지 않습니다(프로젝트의 미확인 주장 금지 규칙). 각 행은 측정 대상과 재현 명령어를 명시합니다. 실행별 전체 데이터와 하드웨어 컨텍스트는 [`bench/results/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/)에 있습니다.

### 호스팅 상호작용 시간(ComputeSDK 피어 세트 기준)

상호작용 시간(TTI)은 모든 호스팅 샌드박스 벤더가 측정되는 공개 [ComputeSDK 벤치마크](https://github.com/computesdk/benchmarks)와 직접 비교 가능한 유일한 지표입니다: `create()`에서 시작하여 샌드박스 내부에서 명령이 실제로 실행되고 결과가 반환될 때까지 측정합니다.

| 제공자 | TTI P50 | 측정 방식 |
|---|---|---|
| northflank | 95.9 ms | ComputeSDK 게시 |
| **mitos** | **96.8 ms** | 당사 하네스, `api.mitos.run` |
| daytona | 136.2 ms | ComputeSDK 게시 |
| e2b | 365.6 ms | ComputeSDK 게시 |

당사의 수치와 피어 테이블을 재현하세요 (피어 수치는 변경 불가능한 커밋에서 ComputeSDK가 게시한 값을 읽은 것이며, 당사가 재실행한 것이 아닙니다):```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

전체 방법과 하드웨어는 [bench/README.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/README.md)에, 결과는 [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)와 [2026-06-21-kvm-perf-correctness.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/2026-06-21-kvm-perf-correctness.md)에 있습니다.

### 웜 클레임 활성화 (엔진, 라운드 트립이 아님)

엔진 자체 웜 샌드박스 활성화(스냅샷 로드 + 포크 정확성 핸드셰이크 + 게스트 준비 완료)는 베어메탈 레퍼런스 노드에서 P50 ~27ms이며, [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh)에서 재현 가능합니다. 이는 위의 종단간 호스팅 TTI보다 작고 다른 숫자입니다. 엔진 수치를 경쟁사의 create-API 수치와 비교하는 것은 범주 오류가 될 수 있으므로 별도로 유지합니다.

## 기능

husk 파드 네이티브 경로가 기본값입니다. 일부 기능은 현재 raw-forkd `엔진 경로`에서만 실행되며, 추적 이슈 링크와 함께 표시되어 있습니다.

### 속도

| 기능 | 제공 사항 | 문서 |
|---|---|---|
| 웜 클레임 활성화 | 베어메탈 레퍼런스 노드에서 P50 ~27ms (스냅샷 로드 + 포크 정확성 핸드셰이크 + 게스트 준비 완료); 스냅샷 복원 ~6-16ms; CoW 페이지 공유를 통해 포크당 추가 메모리 ~3MiB | [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md) |
| 사전 스냅샷 풀 | OCI 이미지를 ext4 루트 파일 시스템으로 평탄화하고 스냅샷 전에 `init` 단계로 워밍하여 클레임 시 콜드 스타트가 없습니다. | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| CoW 메모리 공유 | 포크 전체에서 고유 페이지에 대해서만 비용을 지불하며 복사본에 대해서는 지불하지 않습니다. | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| 콘텐츠 주소 기반 배포 | 포크는 mTLS를 통해 보유자로부터 누락된 sha256 청크만 가져옵니다. 재빌드는 버전 호환성 계약에 따라 델타를 전송합니다. | [docs/snapshot-distribution.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/snapshot-distribution.md) |

### 격리

| 기능 | 제공 사항 | 문서 |
|---|---|---|
| 세션별 하드웨어 격리 | 샌드박스당 전용 커널 (KVM/Firecracker); husk 기본값에서는 각 VM이 자체 비권한, PSA 제한 파드에서 실행되며, 이는 VM별 경계입니다. | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| 무음 비밀 상속 없음 | 비밀을 보유한 샌드박스의 라이브 포크는 명시적으로 옵트인하지 않으면 거부됩니다. 자격 증명은 클레임 시 vsock을 통해 주입되며, 스냅샷에 포함되지 않습니다. | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| 기본 거부 이그레스 | 파드 자체 netns의 인파드 nftables 기본 거부 필터(CNI 독립적), 무조건적인 클라우드 메타데이터(169.254.169.254) 차단, 인파드 DNS 프록시를 통한 IP:포트 및 이름별 템플릿별 허용 목록. 실제 KVM 클러스터에서 종단간 검증됨; 게스트가 시행을 영향을 줄 수 없습니다. | [mitos.run/docs/networking](https://mitos.run/docs/networking) |
| 저장 중 암호화 | 암호화 파쇄 및 KMS 래핑이 있는 범위별 LUKS2 컨테이너(`--enable-encryption` 뒤, 실패 시 폐쇄); HSM 기반 키 및 작업 공간별 범위는 후속 작업입니다. | [docs/encryption.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/encryption.md) |

### 에이전트 DX

| 기능 | 제공 사항 | 문서 |
|---|---|---|
| 차단 exec | 샌드박스 API를 통한 올바른 stdout 및 종료 코드 | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| 스트리밍 exec 및 PTY | 증분 stdout/stderr, 백그라운드 프로세스, 토큰 기반 대화형 WebSocket 터미널 (`engine path`) | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| 코드 인터프리터 | 상태 저장 커널과 풍부한 다중 MIME 결과를 제공하는 `run_code`, 모든 SDK 및 MCP 서버에서 사용 가능; 커널이 husk 기본 이미지에 포함될 때까지 실패 시 폐쇄 `KernelUnavailable` | [mitos.run/docs/mcp](https://mitos.run/docs/mcp) |
| LLM이 읽을 수 있는 오류 | 모든 실패는 `{code, cause, remediation}`을 포함하며, SDK에서 구조화된 `AgentRunError`로 구문 분석됩니다. | [docs/api/errors.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/api/errors.md) |

### Kubernetes 네이티브

| 기능 | 제공 사항 | 문서 |
|---|---|---|
| 선언적 CRD | `SandboxPool`, `Sandbox` (poolRef/fromSandbox/fromRevision 소스), `Workspace`/`WorkspaceRevision` (mitos.run/v1), 볼륨 토폴로지 및 포크 동작 포함 | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| 파드 네이티브 실행 | 각 샌드박스별 VM은 비권한 파드에서 실행됩니다(`/dev/kvm`은 디바이스 플러그인에서, `privileged` 아님). 따라서 CPU/메모리 요청은 스케줄러 진실이며 PSA가 파드를 관리합니다. | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| 용량 인식 스케줄링 | 웜 홀더에 CoW 빈 패킹, CoW 인식 오버커밋 예산, 원자적 슬롯 예약이 있는 `MaxSandboxes` 호스트 DoS 상한, OOM 대신 타입화된 `NoCapacity` 역압력 | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| 수요 기반 자동 확장 | `SandboxPool.spec.autoscale`는 휴면 husk 파드 수를 `clamp(inUse + targetSpare, minWarm, maxWarm)`으로 조정하며, 쓰레기 방지 쿨다운이 있습니다. 고정 풀은 `minWarm == replicas`입니다. | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| 실패 및 GC 의미론 | 클레임 TTL, 고아 VM 정리, 컨트롤러 재시작 조정, 디스크 저널을 통한 forkd 충돌 정리, 노드 손실 처리, 포화 역압력, 모두 CI로 입증됨 | [docs/failure-gc.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/failure-gc.md) |

### 영구 상태

| 기능 | 제공 사항 | 문서 |
|---|---|---|
| 영구 포크 가능 작업 공간 | `Workspace`/`WorkspaceRevision` CRD: 샌드박스와 독립적인 영구적, 버전 관리, 포크 가능한 에이전트 상태. `/workspace`는 시작 시 수화되고, 커밋된 리비전은 종료 시 콘텐츠 주소 저장소를 통해 탈수됩니다. 실제 KVM 클러스터에서 create -> commit -> fork 검증됨 | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| 출력 및 차이 | `spec.lifetime.onTerminate.outputs`는 탈수를 나열된 하위 트리로 좁힙니다. `{diff: true}`는 상위 헤드에 대한 콘텐츠 해시 차이를 기록합니다. | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| Git 랑데부 | `{git}` 출력은 시도별 브랜치를 랑데부 원격으로 푸시합니다(엔진이 푸시, 사람 또는 CI가 병합). 현재 husk에서 최선 노력. | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| 개발 환경 URL | `mitos workspace serve <ws> --pool P`는 작업 공간에 바인딩된 포크된 샌드박스를 웜 클레임하고 준비된 `https://<label>.<expose-domain>/` URL을 반환합니다. 각 포크된 세션은 고유한 URL을 받습니다. | [docs/recipes/dev-environment.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/recipes/dev-environment.md) |

### 운영 가능

| 기능 | 제공 사항 | 문서 |
|---|---|---|
| 메트릭 및 추적 | 노드 및 컨트롤러 Prometheus 메트릭, 클레임당 OpenTelemetry 추적(`--otlp-endpoint`), 전환 가능한 구조화된 감사 로그(`--audit-log`)로 명령/경로 및 바이트 수 기록, 콘텐츠나 비밀은 기록하지 않음 | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| CoW 인식 계량 | 공유 템플릿 페이지 세트는 포크당 한 번이 아니라 한 번만 계산되므로, 과금 및 스케줄링이 정직한 물리적 공간을 반영합니다. | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| 운영자 도구 | `kubectl mitos` 플러그인(`ls` / `ps`) 및 운영 `GET /v1/metering` 보고서 | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| 베어메탈 일급 지원 | Talos + Hetzner가 레퍼런스 플랫폼입니다. | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) |
| 단일 사용자 첫 실행 | 단일 사용자 로그인 게이트가 있는 k3s 빠른 시작 (QA 전용, 프로덕션 아님) | [docs/platforms/k3s-quickstart.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/k3s-quickstart.md) |

## 비교

동일한 하드웨어에서 이 리포지토리의 스크립트로 실제 경쟁사를 대상으로 우리의 하네스가 벤치마크를 재생성할 수 있을 때만 여기에 맞대결 숫자 표를 배치합니다. 해당 하네스는 [#15](https://github.com/mitos-run/mitos/issues/15)입니다. 아래 수치는 **다른 벤더가 공개한 숫자로, 다른 운영, 다른 하드웨어, 다른 방법론에 대한 것입니다.** 당사가 측정한 것이 아니며 맞대결 주장이 아닙니다.

| 런타임 | 공개 수치 (타사, 당사 아님) | 설명하는 운영 |
|---|---|---|
| Mitos (당사 측정) | ~27 ms P50 | 베어메탈 레퍼런스 노드에서 웜 클레임 활성화 |
| E2B | ~150 ms | 샌드박스 생성 |
| Daytona | 90ms 미만 | 스냅샷에서 생성 |
| Modal | 1초 미만 | 샌드박스 생성 |
| CodeSandbox SDK | ~863 ms / ~495 ms | 라이브 포크 / 메모리 재개 |
| Fly Machines | < 1 s | 머신 시작 |

오늘날 비교 가능하고 실제적인 것은 질적 파레토 맵입니다: 오픈 소스, 자체 호스팅 가능, k8s 네이티브, 라이브 스냅샷 포크의 조합은 Mitos가 유일한 축입니다.

| | Mitos | E2B | Modal | Daytona | Morph | Cloudflare | Box | Agent Sandbox | Kata/KubeVirt | raw Firecracker |
|---|---|---|---|---|---|---|---|---|---|---|
| 세션별 하드웨어 격리 | KVM 마이크로VM | 마이크로VM | gVisor | 컨테이너/VM | 마이크로VM | V8 격리 | VM | Kata 옵션 | KVM | KVM |
| 실행 상태의 스냅샷 포크 | 예, 핵심 기본 요소 | 스냅샷/재개 | 메모리 스냅샷 | 아니오 | 예 (Infinibranch) | 아니오 | 디스크 포크 | 아니오 | 아니오 | DIY |
| 웜 풀 밀리초 클레임 | 예 (설계 중심) | 웜 풀 | 웜 풀 | 작업 공간 | 예 | 즉시 격리 | 공개되지 않음 | 1-3s 콜드 | 초 | DIY |
| 영구 포크 가능 작업 공간 | Workspace CRD | 아니오 | 볼륨 | 작업 공간 | 예, 독점 | 예 (디스크) | 아니오 | PVC | PVC | 아니오 |
| Kubernetes 네이티브 API | CRD | SaaS API | SaaS API | SaaS/OSS | SaaS API | SaaS API | 에이전트 네이티브 CLI | CRD | CRD | 아니오 |
| 자체 호스팅 가능 | 예, 모든 KVM 클러스터 | 부분 OSS | 아니오 | OSS 코어 | 아니오 | 아니오 | 아니오 | 예 | 예 | 예 |
| 호스팅 옵션 | 계획됨 (동일 엔진) | 예 | 예 | 예 | 예 | 예 | 예 (전용) | 아니오 | 아니오 | 아니오 |
| 데이터가 인프라에 머무름 | 예 (자체 호스팅) | 아니오 | 아니오 | 부분 | 아니오 | 아니오 | 아니오 | 예 | 예 | 예 |
| 오픈 소스 | Apache 2.0 | 부분 | 아니오 | 부분 | 아니오 | 아니오 | 아니오 | Apache 2.0 | Apache 2.0 | Apache 2.0 |

SaaS 런타임(E2B, Modal, Daytona, Cloudflare)은 빠르지만, 에이전트의 코드, 데이터, 자격 증명이 동등한 기능의 자체 호스팅 경로 없이 타사 인프라에서 실행됩니다. Morph는 올바른 상태 모델(브랜치/복원)을 독점 클라우드로 구축했습니다. Workspace 기본 요소는 동일한 의미론을 오픈 소스로, fork(2) 속도로 제공하는 것을 목표로 합니다. Agent Sandbox(k8s-sigs)는 스냅샷 포크 엔진 없이 Kubernetes API 표준을 선도하고 있으므로, 우리는 경쟁하는 대신 이를 위한 가장 빠른 백엔드가 되기 위해 적합성 퍼사드(`cmd/facade`)를 제공합니다([docs/facade-conformance.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/facade-conformance.md)). Kata, KubeVirt, raw Firecracker는 격리 기본 요소를 제공하고 풀, 포크, 배포, 에이전트 API 계층을 사용자의 문제로 남깁니다.

대안이 귀하가 중요시하는 축에서 우리를 능가하고, 우리가 이를 해결할 로드맵 항목이 없다면, 이는 우리 전략의 버그입니다: 이슈를 열어 주십시오.

## 아키텍처

Mitos는 Firecracker 마이크로VM을 부팅하고, copy-on-write 스냅샷을 통해 포크하며, 전체 라이프사이클을 `mitos.run/v1` API 그룹의 선언적 CRD(`SandboxPool`, `Sandbox`, `Workspace`)로 노출합니다. 샌드박스는 마이크로VM이지 파드가 아닙니다. KVM을 통해 하드웨어 격리를 얻으며, 파드 범위 메커니즘(NetworkPolicy, ResourceQuota, PSA)이 이를 관리하지 않습니다.

구성 요소:

- **controller** (Deployment): CRD를 조정하고, 노드를 선택하며, `forkd`를 구동합니다. 노드별 용량 하트비트에 의해 공급되는 레지스트리를 통해 사용 가능한 포크 노드를 추적합니다.
- **forkd** (DaemonSet): VM을 소유하는 노드별 데몬입니다. 컨트롤러용 gRPC(`:9090`)(포크, 풀 준비, 하트비트)와 exec 및 파일 트래픽용 HTTP 샌드박스 API(`:9091`)를 제공합니다. `/dev/kvm`이 필요하므로 KVM 가능 노드에서만 실행됩니다.
- **guest agent**: 각 마이크로VM 내부의 PID 1입니다. exec, 파일, 환경, 포크 알림을 위한 vsock 프로토콜을 사용합니다.
- **sandbox-server**: Kubernetes 없이도 동일한 포크 엔진을 일반 REST API로 제공하며, 로컬 루프 및 단일 호스트 사용을 위한 것입니다.
- **SDK** (`sdk/python`, `sdk/typescript`, `sdk/go` 등): 호스팅 서비스, 클러스터 또는 `sandbox-server`의 클라이언트입니다.

시스템을 전달하는 두 가지 핫 경로:

- **클레임 경로**: 컨트롤러가 레지스트리에서 웜 노드를 선택하고 gRPC를 통해 `forkd` `Fork`를 호출합니다. 결과 샌드박스는 해당 노드에서 `forkd`의 HTTP API를 통해 Ready를 보고합니다.
- **Exec 경로**: SDK 또는 CLI가 `:9091`에서 `forkd`와 통신하며, 이는 vsock을 통해 VM 내부 게스트 에이전트로 브리징됩니다.

포크는 핵심 기본 요소입니다. 소스 VM은 한 번 스냅샷되고 N개의 자식이 copy-on-write를 통해 해당 스냅샷에서 복원되므로, 각 형제는 웜하고 독립적으로 시작되는 반면, 공유 템플릿 페이지는 한 번 저장되고 계량됩니다. Firecracker는 하드웨어 가상화가 필요하므로, 베어메탈(Hetzner의 Talos가 레퍼런스 플랫폼)이 일급 대상입니다. 클라우드 컨트롤 플레인은 일반 노드에 유지되고 실행은 KVM 가능 머신에 배치됩니다.

## 프로젝트 상태

초기 개발 단계, 1.0 이전(최신 릴리스 `v0.3.0`). 아직 프로덕션에서 신뢰할 수 없는 코드를 실행하지 마십시오: 외부 보안 검토가 이루어지지 않았으며 일부 격리 제어가 아직 열려 있습니다(경계별 정확한 상태는 [위협 모델](https://mitos.run/docs/threat-model) 참조). 컨트롤 플레인은 실제 종단간이며, 모의 엔진 및 실제 Firecracker VM에 대해 CI에서 입증되었고, 단일 노드 Talos KVM 클러스터에서 실행되었습니다.

**실제 KVM 클러스터에서 검증됨(husk 기본값):** 웜 클레임 활성화, 차단 exec, `run_code`가 `KernelUnavailable`로 실패 폐쇄, 자가 복구/재대기, 풀 워밍 및 수요 자동 확장, 라이브 샌드박스 포크(소스 husk 파드가 VM을 스냅샷하고 N개의 자식 파드가 CoW를 통해 복원하며 각각 독립적인 Ready 자식), 영구 포크 가능 작업 공간(create -> commit -> fork), 파드 이그레스 격리(기본 거부, 클라우드 메타데이터 차단, 템플릿별 허용 목록).

**아직 husk 기본값에 없는 추적 사항:** 스트리밍 exec 및 대화형 PTY; 재개 가능한 작업 공간 헤드를 위한 라이브 VM 메모리 스냅샷 후크; S3/암호화 라이브 저장소 선택; husk `{git}` 작업 공간 푸시; 다중 노드 N>1(설계됨, 단일 노드 검증됨).

[ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md)는 완료, 진행 중, 게이트된 항목의 단일 소스입니다. 운영 규칙: 이 리포지토리는 존재하지 않는 시스템을 절대 설명하지 않습니다.

## 로컬 개발 (KVM 불필요)

`mitos dev up`은 모의 컨트롤 플레인에서 로컬 kind 클러스터를 시작하며, `mitos` CLI가 전체 클레임 경로를 구동합니다. 모의 엔진은 클레임을 `Ready`로 조정하고 컨트롤 플레인 디스패치를 실행하지만, 실제 VM 내 `exec`는 `/dev/kvm`이 있는 노드가 필요합니다. 클러스터가 없는 REST 루프의 경우 `go run ./cmd/sandbox-server --mock --addr :8080`을 실행하고 Python SDK를 지정합니다. 전체 kind 연습은 [mitos.run/docs/cli](https://mitos.run/docs/cli)에 있습니다.

## 문서

전체 문서는 **[mitos.run/docs](https://mitos.run/docs)**에 있습니다: 빠른 시작, 아키텍처, SDK 및 CLI 참조, 샌드박스 라이프사이클, 작업 공간, 네트워킹, 위협 모델, 모두 이 리포지토리에서 렌더링됩니다.

전체 긴 꼬리(템플릿, 스냅샷 형식 및 배포, 암호화 및 비밀, 스케줄링 및 밀도, 실패 및 GC, 포크 엔진 정확성, 레시피, 대상 v2 API 사양)는 이 리포지토리의 [`docs/`](https://github.com/mitos-run/mitos/blob/HEAD/docs/)에 있습니다. 벤치마크 방법론은 [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md)에 있습니다.

## 기여

기여를 환영합니다. 규칙은 [CONTRIBUTING.md](https://github.com/mitos-run/mitos/blob/HEAD/CONTRIBUTING.md) 및 [CLAUDE.md](https://github.com/mitos-run/mitos/blob/HEAD/CLAUDE.md)를 참조하고, [ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md)에 대해 추적되는 작업은 [이슈 페이지](https://github.com/mitos-run/mitos/issues)를 참조하십시오.

## 보안

경계별 상태가 포함된 위협 모델은 [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model)에 있습니다. 아직 외부 보안 검토가 이루어지지 않았으며, 문서는 정확히 무엇이 열려 있는지 명시합니다. 취약점을 보고하려면 [SECURITY.md](https://github.com/mitos-run/mitos/blob/HEAD/SECURITY.md)를 참조하십시오.

## 라이선스

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