vmsan

🔥 Firecracker microVM 샌드박스 툴킷

명령줄에서 격리된 Firecracker 마이크로VM을 생성, 관리, 연결하세요. 샌드박싱된 VM을 밀리초 단위로 부팅하고, 명령을 실행하고, 파일을 전송할 수 있습니다 — SSH가 필요 없습니다.

📚 전체 문서를 vmsan.dev에서 읽어보세요

✨ 기능

• ⚡ 밀리초 부팅 — Firecracker 마이크로VM이 200ms 이내에 시작됩니다
• 🔒 보안 격리 — jailer, seccomp, cgroups 및 VM별 네트워크 네임스페이스
• 🖥️ 대화형 셸 — 전체 터미널 지원을 갖춘 WebSocket PTY
• 📂 파일 전송 — SSH 없이 업로드 및 다운로드
• 🐳 도커 이미지 — --from-image를 사용하여 모든 OCI 이미지에서 rootfs 구축
• 🏃 명령 실행 — 스트리밍 출력, 환경 변수 주입, sudo로 명령 실행
• 🧩 다중 런타임 — base, node22, node24, python3.13
• 📸 VM 스냅샷 — VM 상태 저장 및 복원
• 📊 JSON 출력 — 스크립팅 및 자동화를 위한 --json 플래그

📋 사전 요구 사항

• KVM을 지원하는 Linux (x86_64 또는 aarch64)
• 루트/sudo 액세스 (TAP 장치 네트워킹 및 jailer에 필요)
• Docker (소스 설치, 로컬 런타임 재빌드 및 --from-image 필요)

🚀 설치

curl -fsSL https://vmsan.dev/install | bash

이 명령은 모든 것을 ~/.vmsan/에 다운로드하여 설치합니다:

• Firecracker + Jailer (최신 릴리스)
• 리눅스 커널 (vmlinux 6.1)
• Ubuntu 24.04 rootfs (squashfs에서 ext4로 변환)
• vmsan CLI + VM 내 에이전트
• 런타임 이미지(node22, node24, python3.13)를 사전 빌드된 아티팩트로 다운로드

표준 릴리스 설치 시 내장 런타임을 https://artifacts.vmsan.dev/에서 다운로드하며 Docker가 필요하지 않습니다. 소스 설치는 여전히 런타임을 로컬에서 빌드합니다.

curl -fsSL https://vmsan.dev/install | bash -s -- --uninstall

# 의존성 설치
bun install

# VM 내 에이전트 빌드
cd agent && make install && cd ..

# CLI 빌드
bun run build

# 로컬 빌드 연결
mkdir -p ~/.vmsan/bin
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

📖 사용법

# VM 생성 및 시작
vmsan create --runtime node22 --memory 512 --cpus 2

# Docker 이미지에서 VM 생성
vmsan create --from-image node:22-alpine

# 모든 VM 나열
vmsan list

# VM 내에서 명령 실행
vmsan exec <vm-id> ls -la

# PTY를 이용한 대화형 실행
vmsan exec -i <vm-id> bash

# 실행 중인 VM 셸에 연결
vmsan connect <vm-id>

# VM에 파일 업로드
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# VM에서 파일 다운로드
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# 실행 중인 VM 스냅샷
vmsan snapshot create <vm-id>

# 스냅샷 목록
vmsan snapshot list

# 스냅샷에서 VM 복원
vmsan create --snapshot <snapshot-id>

# VM 중지
vmsan stop <vm-id>

# VM 제거
vmsan remove <vm-id>

글로벌 플래그

명령어

⚠️ 알려진 제한 사항

• VM 간 네트워킹 없음 (0.4.0에서 계획)
• 선언적 구성 / vmsan.toml 없음 (0.5.0에서 계획)
• 다중 호스트 지원 없음 (0.7.0에서 계획)
• 네트워크 격리를 위해 원자적 규칙 적용을 사용하는 nftables 사용 (0.2.0 이후)
• DNS 또는 SNI 필터링 없음 (0.3.0에서 계획)
• VM에서 기본적으로 ICMP 차단 (ICMP 터널링 방지)
• DNS를 제외한 UDP 기본 차단 (UDP 유출 방지; QUIC/HTTP3 작동 안 함)
• NTP(UDP 123) 차단 — 시간 동기화에 kvm-clock 사용, 장기 실행 VM 드리프트 가능
• 호스트 방화벽(ufw/firewalld)은 vmsan 트래픽에 대해 명시적 허용 규칙이 필요할 수 있음
• Linux 전용 — KVM 지원 필요
• 기본 플랫폼: Ubuntu 24.04 LTS

🛠️ 개발

# 빌드
bun run build

# 로컬 빌드 연결
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

# 개발 모드 (감시)
bun run dev

# 테스트 실행
bun run test

# 타입 체크
bun run typecheck

# 린트 및 포맷
bun run lint
bun run fmt

🏗️ 아키텍처

bin/            CLI 진입점
src/
  commands/     CLI 하위 명령
  services/     Firecracker 클라이언트, 에이전트 클라이언트, VM 서비스
  lib/          유틸리티 (jailer, 네트워킹, 셸, 로깅)
  errors/       타입화된 오류 시스템
  generated/    Firecracker API 타입 정의
agent/          VM 내에서 실행되는 Go 에이전트
docs/           문서 사이트 (vmsan.dev)

작동 방식

1. vmsan은 Firecracker를 사용하여 보안 격리를 위해 jailer와 함께 경량 마이크로VM을 생성합니다.
2. 각 VM은 자체 /30 서브넷(198.19.{slot}.0/30)을 가진 TAP 네트워크 장치를 얻습니다.
3. Go 기반 에이전트가 VM 내에서 실행되어 명령 실행, 파일 작업 및 셸 액세스를 위한 HTTP API를 노출합니다.
4. CLI는 호스트-게스트 네트워크를 통해 에이전트와 통신합니다.

상태는 ~/.vmsan/에 유지됩니다:

~/.vmsan/
  vms/          VM 상태 파일 (JSON)
  jailer/       Chroot 디렉터리
  bin/          에이전트 바이너리
  kernels/      VM 커널 이미지
  rootfs/       기본 루트 파일시스템
  registry/     Docker 이미지 rootfs 캐시
  snapshots/    VM 스냅샷

⚖️ vmsan 비교

vmsan을 선택해야 하는 이유? Docker는 호스트 커널을 공유합니다 — 컨테이너 이스케이프는 게임 오버를 의미합니다. gVisor는 사용자 공간에서 시스템 콜을 가로채 공격 표면을 줄이지만 완전히 제거하지는 않습니다. Kata Containers는 실제 VM 격리를 제공하지만 복잡한 오케스트레이션(containerd, shimv2, K8s)이 필요합니다. Vagrant는 30초 이상, 수백 MB를 소비하는 전체 VM을 부팅합니다.

vmsan은 Firecracker의 최소 공격 표면(코드 50,000줄 미만)으로 하드웨어 수준 격리를 제공하고 밀리초 단위로 부팅하며 구성 불필요 — 설치 후 바로 사용 가능합니다.

📄 라이선스

Apache-2.0

APACHE-2.0 라이선스에 따라 게시되었습니다. @angelorc 및 커뮤니티가 만들었습니다 💛

🤖 automd로 자동 업데이트됨