smol-machines/smolvm로컬에서 에이전트를 안전하게 실행할 수 있는 임베드 가능하고, 이식성이 뛰어나며, 분기 가능한 가상 머신입니다.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7141/6b8fd173bd97d64ea831a59cdc2b4fd2392dc9b5f2cc90c91594cdb4925a9949.png" alt="smol machines" width="80">
</p>
<p align="center">
<a href="https://discord.gg/E5r8rEWY9J"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
<a href="https://github.com/smol-machines/smolvm/releases"><img src="https://img.shields.io/github/v/release/smol-machines/smolvm?label=Release" alt="Release"></a>
<a href="https://github.com/smol-machines/smolvm/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
<a href="https://www.npmjs.com/package/smolmachines"><img src="https://img.shields.io/npm/v/smolmachines?label=npm&logo=npm" alt="npm"></a>
<a href="https://pypi.org/project/smolmachines/"><img src="https://img.shields.io/pypi/v/smolmachines?label=PyPI&logo=pypi&logoColor=white" alt="PyPI"></a>
<a href="https://crates.io/crates/smolmachines"><img src="https://img.shields.io/crates/v/smolmachines?label=crates.io&logo=rust" alt="crates.io"></a>
</p>
smolvm
======
**AI 에이전트를 위한 브랜치 가능한 microVM.**
가벼운 가상 머신을 소프트웨어, 휴대용 개발 환경, 로컬 샌드박싱에 내장하세요.
설치
----
```bash
brew install smol-machines/tap/smolvm # macOS (Homebrew)
curl -sSL https://smolmachines.com/install.sh | bash # macOS + Linux
```
Windows: `windows-x86_64` [릴리스](https://github.com/smol-machines/smolvm/releases)의 압축을 풀고 `smolvm.exe`를 실행하세요 ([Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/)이 필요합니다). 코딩 에이전트: 설치 후 `smolvm --help`를 실행하여 모든 명령을 확인하세요.
사람과 에이전트를 위한 문서는 [`docs/`](https://github.com/smol-machines/smolvm/blob/main/docs/README.md)에 있으며, 작업별로 폴더가 하나씩 있습니다: 사실을 담은 `README.md`와 에이전트가 따를 수 있는 `SKILL.md`, 그리고 그 스크립트가 각 기능의 참조 페이지 옆에 있습니다.
빠른 시작
-----------
```bash
smolvm machine run --net --image alpine -- uname -a # one-off VM, removed on exit
smolvm machine run --net -it --image alpine -- /bin/sh # interactive shell
```
로컬
-----
자체 커널을 갖춘 실제 VM으로, 노트북이나 자체 서버에서 무료로 사용할 수 있습니다. 1초 이내에 부팅되며 메모리는 탄력적으로 운영되어 호스트는 게스트가 실제로 사용하는 만큼만 커밋합니다. 머신은 재시작 후에도 유지되며, 로컬에서 빌드한 이미지를 포함한 모든 OCI 이미지가 작동합니다.
```bash
smolvm machine create --net --name dev && smolvm machine start --name dev
smolvm machine exec --name dev -- apk add git
docker save myapp | smolvm machine run --image - -- ./app # local image, no registry
```
[Smolfile](https://github.com/smol-machines/smolvm/blob/main/docs/smolfile.md)에서 머신을 선언하세요: 이미지, 리소스, 포트, 마운트 및 네트워크 정책을 하나의 체크인된 파일에 담습니다.
임베드 가능
----------
하나의 `Machine` API로 자신의 코드에서 머신을 구동하세요. SDK는 데몬 없이 로컬 또는 [smol cloud](https://smolmachines.com)에서 여러분의 프로세스 내에서 실행됩니다.
```bash
npm install smolmachines # Node / TypeScript
pip install smolmachines # Python
cargo add smolmachines # Rust
```
```ts
import { Machine } from 'smolmachines';
const m = await Machine.create({ image: 'python:3.12-alpine', network: true });
const r = await m.exec(['python3', '-c', 'print(2 ** 10)']);
console.log(r.stdout); // 1024
await m.delete();
```
소스 및 문서: [smol-machines/smol](https://github.com/smol-machines/smol) · [smolmachines.com/docs/sdk](https://smolmachines.com/docs/sdk)
Branchable
----------
실행 중인 머신을 실행 도중에 저장하고, 되감거나, 동일한 지점에서 계속 실행되는 복사본으로 분기할 수 있습니다. 체크포인트는 RAM, CPU 상태 및 디스크를 캡처하며, 브랜치는 라이브 머신의 copy-on-write 자식입니다.
```bash
smolvm machine create --net --name agent --image alpine
smolvm machine start --name agent --branchable
smolvm machine branch --from agent --name try-1 # live copy-on-write child
smolvm machine checkpoint --name agent -o agent.checkpoint # save it, processes and all
smolvm machine create --name agent2 --from agent.checkpoint # resume later or elsewhere
```
`--from <checkpoint> --at '~N'`로 이전 세대로 되돌리고(`machine checkpoint-log` 참조), [일시 중지 및 재개](https://github.com/smol-machines/smolvm/blob/main/docs/pause-resume.md)를 통해 실행을 잃지 않고 중지할 수 있습니다. arm64 Mac에서 생성한 체크포인트는 arm64 Linux에서 재개됩니다. 자세한 내용은 [Mac에서 Linux로 실행 중인 머신 이동하기](https://github.com/smol-machines/smolvm/blob/main/docs/mac-to-linux.md)를 참조하세요. 더 많은 내용은 [브랜칭](https://github.com/smol-machines/smolvm/blob/main/docs/branching.md)과 [증분 체크포인트](https://github.com/smol-machines/smolvm/blob/main/docs/incremental-checkpoints.md)에서 확인할 수 있습니다.
이식성
--------
어떻게 설정했든 머신을 단일 `.smolmachine` 파일로 패키징하세요. 이를 모든 OCI 레지스트리에 푸시하거나, 아무것도 설치할 필요 없이 200 ms 이내에 부팅되는 자체 포함 실행 파일로 실행하세요.
```bash
smolvm machine stop --name dev && smolvm pack create --from-vm dev -o dev
smolvm pack push --file dev.smolmachine ghcr.io/you/dev:v1
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
```
체크포인트도 이식 가능합니다. 다른 호스트나 smol 클라우드에서 복원할 수 있습니다.
안전
----
각 워크로드는 자체 커널을 가진 하드웨어 격리 VM을 할당받습니다. 네트워킹은 기본적으로 꺼져 있으며, 이그레스는 지정된 호스트로 제한할 수 있고, 코드는 자격 증명을 읽지 않고도 사용할 수 있습니다.
안전은 공동의 책임입니다. smolvm은 경계를 제공합니다. 모든 워크로드에 별도의 VM과 커널을 제공하며, 허용하지 않는 한 호스트에 아무것도 도달하지 않습니다. 그 경계를 무엇이 넘을지는 사용자가 결정합니다. 마운트하는 모든 폴더, 여는 모든 포트, 허용하는 모든 호스트, 전달하는 모든 시크릿 또는 SSH 에이전트는 워크로드가 사용할 수 있게 되므로, 신뢰할 수 없는 워크로드에는 필요한 것만 제공하십시오.
```bash
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -qO- https://google.com # blocked
smolvm machine run --net --image alpine --allow-host-pattern registry.npmjs.org -- wget -qO- https://registry.npmjs.org # exact host only
NOTION_API_KEY=secret_… smolvm machine run --net --image alpine \
--credential [email protected] -- sh -c 'echo $NOTION_API_KEY' # a placeholder
```
[자격 증명 대체](https://github.com/smol-machines/smolvm/blob/main/docs/credential-substitution.md) 및 [보안 모델](https://github.com/smol-machines/smolvm/blob/main/docs/security-model.md)을 참조하세요.
`--allow-host-pattern '*.example.com'`을 사용하면 하위 도메인만 허용되며, `--allow-host example.com`은 에이펙스 도메인과
그 하위 도메인을 허용합니다. `smolvm machine update`는 항목을 추가(`--allow-host`, `--allow-host-pattern`, `--allow-cidr`)하고
제거(`--remove-allow-host`, 추가했을 때의 호스트 또는 패턴 그대로; `--remove-allow-cidr`)하며, 허용 목록으로 시작된
실행 중인 머신에도 적용됩니다. 부여된 권한은 다음 연결 또는 조회에 적용되며, 제거된 호스트의 학습된 주소도 함께 제거됩니다.
작동 방식
------------
각 워크로드는 [Hypervisor.framework](https://developer.apple.com/documentation/hypervisor)(macOS), KVM(Linux), 또는 [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/)(Windows)에서 자체 게스트 커널을 갖춘 하드웨어 가상화 VM에서 실행됩니다. [libkrun](https://github.com/containers/libkrun)이 VMM이며 [libkrunfw](https://github.com/smol-machines/libkrunfw)가 게스트 커널을 제공합니다. 이미지는 [OCI](https://opencontainers.org/) 형식을 사용하므로 Docker Hub, ghcr.io 또는 다른 레지스트리에 있는 무엇이든 Docker 데몬 없이 마이크로VM으로 부팅됩니다.
기본값: 4 vCPU, 8 GiB RAM. 메모리는 virtio balloon을 통해 탄력적으로 운용되며 유휴 vCPU는 하이퍼바이저에서 절전 상태가 되므로, 과다 프로비저닝 비용은 거의 없습니다. `--cpus`와 `--mem`으로 재정의할 수 있습니다.
비교
----------
| | smolvm | 컨테이너 | Colima | QEMU | Firecracker | Kata |
|---------------------|--------|------------|--------|------|-------------|------|
| 워크로드 경계 | VM + 게스트 커널 | 네임스페이스 + 공유 커널 | 공유 VM 내부의 네임스페이스 | VM + 게스트 커널 | VM + 게스트 커널 | 컨테이너당 VM |
| 부팅 시간 | 에이전트 준비까지 <200ms | ~100ms | ~수 초 | ~15-30s | <125ms | ~500ms |
| 아키텍처 | 라이브러리 (libkrun) | 데몬 | 데몬 (VM 내) | 프로세스 | 프로세스 | 런타임 스택 |
| 워크로드별 VM | 예 | 아니요 | 아니요 (공유) | 예 | 예 | 예 |
| macOS 네이티브 | 예 | Docker VM 경유 | 예 (krunkit) | 예 | 아니요 | 아니요 |
| 임베디드 SDK | 예 | 아니요 | 아니요 | 아니요 | 아니요 | 아니요 |
| 이식 가능한 아티팩트 | `.smolmachine` | 이미지 (데몬 필요) | 아니요 | 아니요 | 아니요 | 아니요 |
플랫폼 지원
----------------
| 호스트 | 게스트 | 요구 사항 |
|------|-------|-------------|
| macOS Apple Silicon | arm64 Linux | macOS 11+ |
| macOS Intel | x86_64 Linux | 공개된 릴리스 빌드 없음; 테스트되지 않음 |
| Linux x86_64 | x86_64 Linux | KVM (`/dev/kvm`) |
| Linux aarch64 | aarch64 Linux | KVM (`/dev/kvm`) |
| Windows x86_64 | x86_64 Linux | Windows Hypervisor Platform (WHP) 활성화 |
Windows는 이식 가능한 체크포인트, 일시 중지/재개, 그리고 `--freeze-source`를 사용한 분기를 지원합니다. GPU 가속은 여전히 사용할 수 없습니다. [알려진 제한 사항](https://github.com/smol-machines/smolvm/blob/main/docs/limitations.md)을 참조하세요.
추가 정보
----
* [Kubernetes](https://github.com/smol-machines/smolvm/blob/main/docs/kubernetes.md): `RuntimeClass`를 통해 파드를 마이크로VM으로 실행합니다.
* [GPU 및 CUDA](https://github.com/smol-machines/smolvm/blob/main/docs/gpu.md): virtio-gpu / Venus를 통한 Vulkan, 그리고 CUDA API 리모팅.
* [예제](https://github.com/smol-machines/smolvm/blob/main/examples): python, node, docker-in-vm, local-llm, headless-browser, doom.
* [개발](https://github.com/smol-machines/smolvm/blob/main/docs/DEVELOPMENT.md) · 사용자 문서는 [smolmachines.com/docs](https://smolmachines.com/docs/)에 있으며, [smol-machines/docs](https://github.com/smol-machines/docs)에서 작성됩니다 (수정 사항은 그곳에서 환영합니다; 런타임 버그는 이곳에 남겨 주세요).
smolvm은 [smol machines](https://smolmachines.com) 뒤에 있는 오픈소스 런타임이며, SmolVM이라는 이름의 다른 프로젝트와 제휴 관계가 없습니다.
[Apache-2.0](https://github.com/smol-machines/smolvm/blob/main/LICENSE) · 제작: [@binsquare](https://github.com/BinSquare) · [twitter](https://x.com/binsquares) · [github](https://github.com/smol-machines/smolvm)