smolvm

AI 에이전트를 위한 브랜치 가능한 microVM. 가벼운 가상 머신을 소프트웨어, 휴대용 개발 환경, 로컬 샌드박싱에 내장하세요.

설치

brew install smol-machines/tap/smolvm                  # macOS (Homebrew)
curl -sSL https://smolmachines.com/install.sh | bash   # macOS + Linux

Windows: windows-x86_64 릴리스의 압축을 풀고 smolvm.exe를 실행하세요 (Windows Hypervisor Platform이 필요합니다). 코딩 에이전트: 설치 후 smolvm --help를 실행하여 모든 명령을 확인하세요.

사람과 에이전트를 위한 문서는 docs/에 있으며, 작업별로 폴더가 하나씩 있습니다: 사실을 담은 README.md와 에이전트가 따를 수 있는 SKILL.md, 그리고 그 스크립트가 각 기능의 참조 페이지 옆에 있습니다.

빠른 시작

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 이미지가 작동합니다.

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에서 머신을 선언하세요: 이미지, 리소스, 포트, 마운트 및 네트워크 정책을 하나의 체크인된 파일에 담습니다.

임베드 가능

하나의 Machine API로 자신의 코드에서 머신을 구동하세요. SDK는 데몬 없이 로컬 또는 smol cloud에서 여러분의 프로세스 내에서 실행됩니다.

npm install smolmachines     # Node / TypeScript
pip install smolmachines     # Python
cargo add smolmachines       # Rust

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 · smolmachines.com/docs/sdk

Branchable

실행 중인 머신을 실행 도중에 저장하고, 되감거나, 동일한 지점에서 계속 실행되는 복사본으로 분기할 수 있습니다. 체크포인트는 RAM, CPU 상태 및 디스크를 캡처하며, 브랜치는 라이브 머신의 copy-on-write 자식입니다.

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 참조), 일시 중지 및 재개를 통해 실행을 잃지 않고 중지할 수 있습니다. arm64 Mac에서 생성한 체크포인트는 arm64 Linux에서 재개됩니다. 자세한 내용은 Mac에서 Linux로 실행 중인 머신 이동하기를 참조하세요. 더 많은 내용은 브랜칭과 증분 체크포인트에서 확인할 수 있습니다.

이식성

어떻게 설정했든 머신을 단일 .smolmachine 파일로 패키징하세요. 이를 모든 OCI 레지스트리에 푸시하거나, 아무것도 설치할 필요 없이 200 ms 이내에 부팅되는 자체 포함 실행 파일로 실행하세요.

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 에이전트는 워크로드가 사용할 수 있게 되므로, 신뢰할 수 없는 워크로드에는 필요한 것만 제공하십시오.

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

자격 증명 대체 및 보안 모델을 참조하세요. --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(macOS), KVM(Linux), 또는 Windows Hypervisor Platform(Windows)에서 자체 게스트 커널을 갖춘 하드웨어 가상화 VM에서 실행됩니다. libkrun이 VMM이며 libkrunfw가 게스트 커널을 제공합니다. 이미지는 OCI 형식을 사용하므로 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) 활성화