smolvm

격리(isolation)를 기본으로 소프트웨어를 배포하고 실행합니다.

이 CLI 도구를 사용하면 다음을 할 수 있습니다:

1. 로컬에서 커스텀 Linux 가상 머신을 관리하고 실행할 수 있습니다: 1초 미만의 콜드 스타트, 크로스 플랫폼(macOS, Linux, Windows), 탄력적인 메모리 사용.
2. 상태를 가진 가상 머신을 단일 파일(.smolmachine)로 패킹하여 지원되는 모든 플랫폼에서 다시 복원할 수 있습니다.

설치

# 설치 (macOS + Linux)
curl -sSL https://smolmachines.com/install.sh | bash

# 코딩 에이전트용 — 설치 + 모든 명령어 확인
curl -sSL https://smolmachines.com/install.sh | bash && smolvm --help

또는 GitHub Releases에서 다운로드하여 ~/.local/share/에 넣으세요.

Windows: windows-x86_64 릴리스를 다운로드하고(krun.dll + libkrunfw.dll 포함), 압축을 풀고 smolvm.exe를 실행하세요. Windows Hypervisor Platform (WHP) 기능이 활성화되어 있어야 합니다.

빠른 시작

# 임시 VM에서 명령 실행 (종료 후 정리됨)
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"

# 인터랙티브 셸
smolvm machine run --net -it --image alpine -- /bin/sh
# VM 내부에서: apk add sl && sl && exit

Smolfile

Smolfile은 TOML로 머신을 선언합니다 — Dockerfile이나 cloud-init 파일과 동일하지만, 전체 VM을 위한 것입니다: 이미지, 리소스, 네트워크 정책, 마운트, 포트, 설정 명령이 하나의 체크인된 파일에 포함됩니다.

image = "python:3.12-alpine"
net = true
cpus = 4
memory = 4096

ports = ["8000:8000", "5173-5180:5173-5180"]
volumes = ["./src:/app"]
init = ["pip install -r /app/requirements.txt"]

[network]
allow_hosts = ["api.stripe.com", "pypi.org"]

[auth]
ssh_agent = true

smolvm machine create --name myvm -s Smolfile   # 또는 --smolfile <PATH>
smolvm machine start --name myvm

포트 매핑은 단일 포트("8080"), 명시적 매핑("8080:80"), 또는 동일 길이의 1:1 범위("5173-5180:5173-5180")를 허용합니다. 머신은 최대 64개의 구체적인 매핑을 게시할 수 있습니다.

알 수 없는 키는 무시되지 않고 거부되므로, 오타는 조용히 아무것도 하지 않는 대신 생성 시점에 실패합니다.

일반 키: image, cpus, memory, net, ports, volumes, env, init, workdir, gpu, cuda, docker_socket, storage, overlay, 그리고 [network], [dev], [auth], [health], [restart], [service] 테이블.

머신을 재사용 가능한 이미지로 스냅샷

환경을 유지하기 위해 Dockerfile이 필요하지 않습니다. 원하는 대로 머신을 설정하세요 — 수동으로 또는 Smolfile에서 — 그런 다음 중지된 머신을 .smolmachine 아티팩트로 패킹하고 OCI 레지스트리에 푸시합니다:

smolvm machine shell --name myvm          # 인터랙티브하게 설치 및 구성
smolvm machine stop  --name myvm
smolvm pack create --from-vm myvm -o myvm
smolvm pack push --file myvm.smolmachine ghcr.io/you/myvm:v1

그러면 누구나 풀(pull)하여 동일한 머신을 부팅할 수 있습니다:

smolvm pack pull ghcr.io/you/myvm:v1

작동하는 Smolfile 예제: python · node · docker-in-vm · local-llm · headless-browser · doom

이 용도로 사용

신뢰할 수 없는 코드 샌드박싱 — 신뢰할 수 없는 프로그램을 하드웨어 격리 VM에서 실행합니다. 호스트 파일시스템, 네트워크, 자격 증명은 하이퍼바이저 경계로 분리됩니다.

# 네트워크는 기본적으로 꺼져 있음 — 신뢰할 수 없는 코드는 외부 통신 불가
smolvm machine run --image alpine -- nslookup example.com
# 실패 — 네트워크 접근 없음

# 이그레스(egress) 잠금 — 특정 호스트만 허용
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
# 작동 — 허용된 호스트

smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com
# 실패 — 허용 목록에 없음

휴대용 실행 파일로 패킹 — 모든 워크로드를 자체 포함 바이너리로 변환합니다. 모든 종속성이 사전 내장되어 있습니다 — 설치 단계 없음, 런타임 다운로드 없음, <200ms 부팅.

smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — 격리됨, pyenv/venv/conda 불필요

로컬 컨테이너 이미지 사용 — CI, 에어갭(air-gapped) 호스트, 빠른 반복을 위해. --image에 docker save / podman save 아카이브를 제공하거나, stdin으로 파이프하거나, 압축 해제된 rootfs 디렉토리를 가리키세요. 이미지 작업은 컨테이너 도구에 위임되고, smolvm은 결과만 부팅합니다.

# 로컬에서 빌드, push/pull 없이 VM에서 실행
docker build -t myapp .
docker save myapp | smolvm machine run --image - -- ./app

# 아카이브 파일에서 (네트워크 없이 부팅)
smolvm machine run --image ./myapp.tar -- ./app

# 이미 압축 해제된 rootfs 디렉토리에서
smolvm machine run --image ./rootfs/ -- ./app

개발용 영구 머신 — 생성, 중지, 시작. 설치된 패키지는 재시작 후에도 유지됩니다.

smolvm machine create --net --name myvm
smolvm machine start --name myvm
smolvm machine exec --name myvm -- apk add sl
smolvm machine exec --name myvm -it -- /bin/sh
# 내부에서: sl, ls, uname -a — 'exit' 입력하여 종료
smolvm machine stop --name myvm

게스트에 개인 키를 복사하지 않고 git과 SSH 사용. 호스트 SSH 에이전트를 VM으로 포워딩합니다. 게스트는 소켓이 사용 가능한 동안 포워딩된 키로 서명을 요청할 수 있으므로, 신뢰하는 워크로드에만 포워딩하세요. 호스트에서 SSH 에이전트가 실행 중이어야 합니다(ssh-add -l로 확인).

smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# 호스트 키 목록 표시; 개인 키 자료는 호스트 에이전트에 남아 있음

smolvm machine exec --name myvm -- git clone [email protected]:org/private-repo.git

파일로 환경 선언 — 재현 가능한 머신 구성은 위의 Smolfile을 참조하고, Dockerfile을 작성하지 않고 구성된 머신을 재사용 가능한 .smolmachine 이미지로 스냅샷하는 방법도 참조하세요.

작동 방식

각 워크로드는 Hypervisor.framework(macOS), KVM(Linux), 또는 Windows Hypervisor Platform(Windows)에서 자체 게스트 커널을 가진 하드웨어 가상화 VM에서 실행됩니다. libkrun이 VMM이고 libkrunfw가 게스트 커널을 제공합니다. .smolmachine으로 패킹하면 호스트 아키텍처가 일치하는 모든 곳에서 종속성 없이 실행됩니다.

이미지는 Docker가 사용하는 것과 동일한 오픈 표준인 OCI 형식을 사용합니다. Docker Hub, ghcr.io 또는 기타 OCI 레지스트리의 모든 이미지를 풀(pull)하여 microVM으로 부팅할 수 있습니다. Docker 데몬이 필요 없습니다.

기본값: 4 vCPU, 8 GiB RAM. 메모리는 virtio balloon을 통해 탄력적으로 사용됩니다 — 호스트는 게스트가 실제로 사용하는 만큼만 커밋하고 나머지는 자동으로 회수합니다. vCPU 스레드는 유휴 상태일 때 하이퍼바이저에서 절전하므로, 과잉 프로비저닝 비용이 거의 없습니다. --cpus와 --mem으로 재정의하세요.

보안 모델

smolvm은 각 워크로드에 별도의 VM과 게스트 커널을 제공하여 게스트/호스트 경계를 강화합니다. 그 자체로는 강화된 다중 사용자 제어 플레인이 아닙니다:

• smolvm CLI 및 VMM 프로세스는 호출한 호스트 사용자의 권한으로 실행됩니다. 해당 사용자 계정, 호스트 OS, 하이퍼바이저 백엔드, libkrun, smolvm은 신뢰 컴퓨팅 베이스(TCB)에 포함됩니다.
• --volume으로 전달된 호스트 디렉토리는 요청된 접근 권한으로 게스트에 의도적으로 노출됩니다. 신뢰할 수 없는 워크로드에 비밀 또는 민감한 경로를 마운트하지 마세요.
• --ssh-agent는 개인 키 자료를 게스트에 복사하지 않지만, 게스트에 포워딩된 에이전트 소켓에 대한 접근 권한을 부여하므로 VM이 실행되는 동안 서명을 요청할 수 있습니다.
• 네트워킹은 기본적으로 비활성화됩니다. --net, 포트 포워딩 또는 호스트 서비스를 활성화하면 워크로드의 도달 가능한 표면이 확장됩니다.
• 독립형 로컬 사용에서 smolvm의 상태 및 제어 엔드포인트는 호출 사용자의 환경으로 범위가 제한됩니다. 적대적인 로컬 공동 테넌트의 경우 VMM 프로세스 주변에 호스트 수준 계정 분리와 OS 컨테이너 격리를 추가하세요. 이 섹션은 별도의 smolmachines 클라우드 제어 플레인 또는 해당 테넌트 격리 보장을 설명하지 않습니다.
• 릴리스 아카이브는 SHA-256 체크섬을 게시하며, 설치 프로그램은 체크섬 파일을 사용할 수 있을 때 불일치를 거부합니다. 릴리스는 현재 서명되거나 출처 증명(provenance attestation)이 포함되지 않으며, 설치 프로그램은 체크섬 파일을 다운로드할 수 없을 때 설치를 허용합니다.

게스트의 root를 신뢰할 수 없는 것으로 취급하세요. VM 경계는 호스트에 대한 직접 접근을 제한하며, 마운트, 네트워크 접근, 포트, SSH 에이전트 접근을 포함한 모든 명시적으로 포워딩된 기능은 워크로드의 권한의 일부가 됩니다.

비교

플랫폼 지원

알려진 제한 사항

• 네트워크는 옵트인입니다(machine create에서 --net). TCP/UDP만 지원, ICMP 없음.
• 볼륨 마운트: 디렉토리만 가능(단일 파일 불가). /workspace에 마운트(-v /host/dir:/workspace)하면 기본 스토리지 디스크 워크스페이스보다 우선합니다 — 호스트 디렉토리가 대신 사용됩니다.
• macOS: 바이너리는 Hypervisor.framework 자격(entitlements)(com.apple.security.hypervisor)으로 서명되어야 합니다. 배포된 릴리스는 서명되어 있습니다. 재서명하거나 새로 빌드한 바이너리는 조용히 자격을 잃고 모든 VM 시작이 krun_start_enter returned: -22 (EINVAL)로 실패합니다. 재서명하세요(임시 서명도 가능): codesign --force --sign - --entitlements hv.entitlements <smolvm-bin> 여기서 hv.entitlements는 <key>com.apple.security.hypervisor</key><true/>를 포함하는 plist입니다.
• --ssh-agent는 호스트에서 SSH 에이전트가 실행 중이어야 합니다(SSH_AUTH_SOCK이 설정되어 있어야 함).
• GPU 가속은 GPU=1로 빌드된 libkrun과 호스트의 virglrenderer + Vulkan 드라이버가 필요합니다(아래 GPU 가속 참조).
• Windows: --net은 다른 플랫폼과 동일하게 작동합니다(virtio-net + 인바운드 포트 포워딩, 아웃바운드 전용 VM용 TSI). machine exec / 인터랙티브 세션 및 machine stats도 동일합니다. Windows에서 아직 사용할 수 없는 것: GPU 가속 및 machine fork / 스냅샷. Pack create는 smolvm.exe 옆에 storage-template.ext4 / overlay-template.ext4가 필요합니다(Windows에는 호스트 mkfs.ext4가 없음).

GPU 가속

smolvm은 virtio-gpu / Venus(Vulkan-over-virtio)를 통해 호스트 GPU를 게스트에 노출합니다. 게스트 워크로드는 실제 Vulkan 장치를 볼 수 있습니다. Linux + Intel에서 다음과 같이 렌더링됩니다:

ANGLE (Intel, Vulkan 1.4 (Virtio-GPU Venus (Intel(R) UHD Graphics ...)), venus)

호스트 요구 사항

macOS — virglrenderer와 MoltenVK는 smolvm 배포판에 번들되어 있습니다. 추가 설치가 필요 없습니다.

Linux — virglrenderer와 호스트 Vulkan 드라이버를 시스템 패키지 관리자에서 설치해야 합니다:

virglrenderer는 호스트 GPU 드라이버 스택의 libEGL과 libdrm에 의존합니다 — 이들은 하드웨어별로 다르며 번들할 수 없습니다. GPU 지원 Linux 호스트는 GPU 드라이버를 통해 이미 설치되어 있을 것입니다.

사용법

# CLI
smolvm machine run --gpu --image alpine -- vulkaninfo --summary

# Smolfile
# gpu = true
# gpu_vram = 2048   # MiB, 기본값 4096

게스트 Vulkan 로더는 virtio ICD를 가리켜야 합니다:

export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.json

헤드리스 브라우저 예제

헤드리스 VM 내에서 하드웨어 가속 WebGL을 위해 ANGLE + Venus를 사용하는 작동하는 Chromium 설정은 examples/headless-browser/를 참조하세요.

CUDA API 리모팅

--gpu와 --cuda는 서로 다른 인터페이스를 제공합니다. --gpu는 virtio-gpu / Venus를 통해 Vulkan을 노출합니다. CUDA를 제공하지 않습니다. --cuda는 CUDA API 리모팅을 활성화합니다: 드라이버 없는 게스트 셰임(shim)이 vsock을 통해 CUDA 호출을 호스트 프로세스로 포워딩하고, 호스트 프로세스는 호스트의 NVIDIA 드라이버를 통해 실행합니다.

CUDA 리모팅은 호스트에 NVIDIA GPU와 작동하는 NVIDIA 드라이버가 필요합니다. GPU 패스스루가 아닙니다: 게스트는 물리적 장치도 NVIDIA 드라이버도 받지 않습니다.

Fork가 많은 Linux 호스트는 업스트림 KVM 수정 916b7f4가 포함된 커널을 사용해야 합니다. 영향을 받는 커널은 호스트 메모리가 충분해도 첫 번째 KVM_RUN에서 간헐적으로 ENOMEM을 보고할 수 있습니다. smolvm은 노출을 줄이고 실패한 워커를 교체하지만, 커널 업데이트가 확실한 해결책입니다.

VM 경계는 여전히 워크로드의 CPU, 메모리, 파일시스템을 격리합니다. GPU 접근은 호스트 프로세스와 공유 호스트 GPU에 의해 중재되므로, GPU 격리는 하드웨어 또는 VM 경계가 아닌 프로세스 수준으로 유지됩니다. CUDA 리모팅을 강화된 다중 테넌트 GPU 격리 경계로 취급하지 마세요.

설계, 트레이드오프 및 패스스루와의 비교는 GPU access by API remoting: how a driverless microVM runs CUDA를 참조하세요.

개발

docs/DEVELOPMENT.md를 참조하세요.

Apache-2.0 · 제작: @binsquare · twitter · github