서론 (Introduction)

"에이전트에게 라이브러리 형태의 운영체제를 제공하십시오. 샌드박스(sandbox)보다 92배 빠른 콜드 스타트(cold start), 47배 적은 메모리, 254배 저렴한 비용을 보장합니다."

이 글은 "하루에 하나씩 오픈 소스 프로젝트(One Open Source Project a Day)" 시리즈의 137번째 기사입니다. 오늘의 프로젝트는 agentOS입니다. 이는 npm 패키지로 배포되는 AI 에이전트 런타임(runtime)으로, 외부 샌드박스(sandbox), microVM 또는 컨테이너(container)를 실행할 필요 없이 여러분의 Node.js 백엔드 내부에서 AI 코딩 에이전트를 실행할 수 있게 해줍니다.

AI 에이전트에게 실행 환경을 제공하는 것은 인프라 문제로 변모하고 있습니다. E2B, Daytona, Modal 및 유사한 샌드박스(sandbox) 서비스들은 일반적으로 수백 밀리초에서 수 초에 달하는 콜드 스타트(cold start), 인스턴스당 최소 1GB의 메모리, 그리고 분당 과금 방식을 가집니다. agentOS의 접근 방식은 다음과 같습니다. 만약 에이전트의 VM이 전체 Linux 환경 대신 V8 isolates + WebAssembly를 기반으로 구축된다면, 해당 VM은 프로세스 내부에 임베드(embed)될 수 있습니다. 이를 통해 밀리초 단위의 콜드 스타트(cold start), 수십 메가바이트의 메모리, 그리고 두 자릿수(two orders of magnitude) 더 낮은 비용을 달성할 수 있습니다.

4,265 Stars. Apache 2.0. Rivet Dev에 의해 유지 관리됩니다.

학습 내용

• agentOS의 VM 격리 모델: V8 isolates + WebAssembly, 그리고 전체 샌드박스(sandbox)와의 핵심 차이점
• 성능 벤치마크(benchmarks): E2B 및 Daytona와의 콜드 스타트(cold start), 메모리, 비용 비교
• 핵심 기능: 바인딩(bindings), 파일 시스템 마운트(filesystem mounts), 권한(permissions), ACP를 통한 세션(sessions)
• 내장된 에이전트 지원: Pi, Claude Code, Codex, OpenCode
• 어떤 시나리오에서 agentOS가 필요하며, 언제 실제로 전체 샌드박스(sandbox)가 필요한지

사전 요구 사항

• 기본적인 Node.js/TypeScript 숙련도
• AI 에이전트 도구 호출(tool-calling)에 대한 일반적인 이해
• V8 또는 WebAssembly가 무엇인지 알면 도움이 되지만, 필수 사항은 아님

프로젝트 배경 (Project Background)

개요 (Overview)

agentOS는 npm 패키지(@rivet-dev/agentos)입니다. 설치 후, TypeScript/Node.js 코드에서 직접 VM 인스턴스를 생성하고, 해당 VM 내부에서 AI 에이전트를 실행하며, 에이전트는 바인딩(bindings)을 통해 여러분의 JavaScript 함수를 호출합니다. 이 과정에서 네트워크 홉(network hop)은 필요하지 않습니다.

아키텍처 (Architecture): 각 VM은 가상 커널(virtual kernel) — 가상 파일 시스템 (virtual filesystem), 프로세스 테이블 (process table), 파이프 (pipes), PTY, 그리고 가상 네트워크 스택 (virtual network stack) — 을 관리하는 신뢰할 수 있는 사이드카 (sidecar) 프로세스에 의해 소유됩니다. 게스트의 모든 시스템 콜 (syscall)은 이 사이드카를 통해 프록시 (proxy)되며, 게스트가 수행하는 그 어떤 작업도 실제 호스트 (host)에 영향을 주지 않습니다. 게스트 JavaScript는 네이티브 V8 (full JIT)에서 실행되며, 컴파일된 도구들은 WebAssembly로 실행됩니다. 여러 VM이 하나의 사이드카 프로세스를 공유하므로, 추가되는 각 VM은 새로운 OS 프로세스가 아닌 하나의 V8 아이솔레이트 (isolate)와 커널 상태 (kernel state)만큼의 비용만 발생합니다.

저자 / 팀 (Author / Team)

• 회사 (Company): Rivet Dev
• 주요 언어 (Primary language): Rust (코어 런타임 (core runtime)) + TypeScript (SDK)
• 라이선스 (License): Apache-2.0
• 웹사이트 (Website): agentos-sdk.dev

프로젝트 통계 (Project Stats)

• ⭐ GitHub Stars: 4,265+
• 🍴 Forks: 214+
• 📄 License: Apache-2.0
• 📅 생성일 (Created): 2024-02-07

퀵 스타트 (Quick Start)

npm install @rivet-dev/agentos @agentos-software/pi

서버 생성 (server.ts):

import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";

...

클라이언트 생성 (client.ts):

import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";

...

둘 다 실행:

# 터미널 1: 서버 시작
npx tsx server.ts

...

VM 내부에서 Node.js 및 셸 (shell)을 직접 실행:

await handle.writeFile("/hello.mjs", 'import fs from "fs"; fs.writeFileSync("/out.txt", "hi")');
await handle.exec("node /hello.mjs");

...

성능 벤치마크 (Performance Benchmarks)

벤치마크 데이터는 2026년 3월 30일에 측정되었습니다:

콜드 스타트 (Cold Start)

agentOS는 Intel i7-12700KF에서 측정되었습니다. E2B는 2026년 3월 30일 기준 가장 빠른 메인스트림 샌드박스 (sandbox)입니다.

인스턴스당 메모리 (Memory Per Instance)

실행 초당 비용 (Cost Per Execution-Second) (자체 호스팅, 전체 코딩 에이전트)

Daytona 기준선: $0.0504/vCPU-h + $0.0162/GiB-h (최소 1 vCPU + 1 GiB).

격차가 이토록 큰 이유: 샌드박스 서비스들은 최소 인스턴스 사양이 1 vCPU + 1 GiB입니다. 즉, 단 하나의 ls 명령어를 실행하더라도 인스턴스 전체 비용을 지불해야 합니다. 반면 agentOS의 VM 하한선은 하나의 V8 격리체 (isolate)와 커널 상태 (kernel state)입니다. 단순한 셸 명령어는 22 MB만을 사용합니다. 이는 최적화의 문제가 아니라, 격리 계층 (isolation-layer) 선택에서 오는 구조적 격차입니다.

핵심 기능 (Core Features)

바인딩 (Bindings): 에이전트가 귀하의 함수를 직접 호출

이것은 기존 샌드박스와의 가장 근본적인 아키텍처 차이점입니다.

전통적인 샌드박스에서 귀하의 데이터에 접근하거나 로직을 호출하는 에이전트는 네트워크 API를 거쳐야 합니다: 샌드박스 → HTTP → 귀하의 백엔드. 이 과정에서 자격 증명 (Credentials)이 샌드박스로 전달되고, 지연 시간 (latency)이 증가하며, 추가적인 공격 표면 (attack surface)이 발생합니다.

agentOS 바인딩:

const vm = agentOS({
  software: [pi],
  bindings: {
...

VM 내부의 에이전트가 get_user_data 123을 실행하면, 일반적인 셸 명령어처럼 동작하지만 실제로는 호스트에서 정의한 TypeScript 함수를 호출하는 것입니다. 자격 증명과 데이터베이스 연결은 VM 내부로 절대 들어가지 않습니다.

파일 시스템 마운트 (Filesystem Mounts)

부팅 시 또는 런타임에 동적으로 마운트합니다:

const vm = agentOS({
  software: [pi],
  mounts: [
...

세밀한 권한 제어 (Granular Permissions)

네트워크 외부 송신 (Network egress)은 기본적으로 거부되며, 필요에 따라 허용합니다:

const vm = agentOS({
  software: [pi],
  permissions: {
...

ACP를 통한 세션 (Sessions via ACP)

agentOS는 **ACP (Agent Client Protocol)**를 통해 에이전트 세션을 관리합니다:

• 추가 코드 없이 세션 자동 유지 (auto-persist)
• 중단된 세션 재개 가능
• 디버깅 및 비교를 위해 모든 에이전트에 대해 통일된 트랜스크립트 (transcript) 형식 제공

Cron 및 Webhooks

// 에이전트 작업 스케줄링
registry.cron("0 9 * * *", async () => {
  const handle = client.vm.getOrCreate("daily-report");
...

멀티플레이어 (Multiplayer)

여러 클라이언트가 동일한 에이전트를 실시간으로 관찰하고 협업할 수 있습니다:

const conn1 = handleA.connect(); // 읽기 전용 관찰자 (read-only observer)
const conn2 = handleB.connect(); // 프롬프트 전송도 가능

에이전트 간 위임 (Agent-to-Agent Delegation)

const vm = agentOS({
  software: [pi, claudeCode],
  bindings: {
...

내장 에이전트 레지스트리 (Built-In Agent Registry)

에이전트와 도구들은 npm 패키지로 배포됩니다:

일반적인 POSIX 유틸리티 (coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip)가 기본적으로 포함되어 제공됩니다.

agentOS vs 풀 샌드박스 (Full Sandboxes): 언제 무엇을 사용할 것인가

agentOS의 자체 문서에서는 이 둘이 경쟁 관계가 아닌 상호 보완적인 관계임을 명시하고 있습니다.

다음의 경우 agentOS를 선택하세요:

• 에이전트가 백엔드의 데이터베이스나 함수를 호출해야 할 때 (직접적인 바인딩 (bindings), 네트워크 홉 (network hop) 없음)
• 높은 동시성 (concurrency) 또는 고빈도 에이전트 작업이 필요할 때 (낮은 메모리 사용량 = 호스트당 더 많은 인스턴스 실행 가능)
• 콜드 스타트 지연 시간 (latency)이 중요할 때 (사용자 대상 실시간 워크플로우)
• 셀프 호스팅 (Self-hosted)을 원하며, 샌드박스 업체의 과금 체계를 원하지 않을 때

다음의 경우 풀 샌드박스를 선택하세요:

• 네이티브 컴파일 (C/C++/Rust 툴체인)을 실행해야 할 때
• 전체 개발 서버를 시작해야 할 때 (내부에 Node/Python HTTP 서버 포함)
• 실제 브라우저가 필요할 때 (단순한 헤드리스 (headless) API가 아닌 경우)
• 워크로드가 이미 무거워 샌드박스 비용이 수용 가능한 수준일 때

두 가지를 함께 사용하기 (샌드박스 마운팅 (sandbox mounting)):

const vm = agentOS({
  software: [pi],
  // 필요할 때 전체 샌드박스를 실행하고, 해당 파일시스템을 마운트합니다
...

기본적으로는 경량 agentOS VM을 사용하고, 워크로드가 진정으로 실제 Linux를 필요로 할 때 전체 샌드박스를 마운트하여 사용하세요.

리소스 (Resources)

공식 링크 (Official Links)

• 🌟 GitHub: rivet-dev/agentos
• 🌐 웹사이트 (Website): agentos-sdk.dev
• 📖 빠른 시작 (Quickstart): agentos-sdk.dev/docs/quickstart
• 📦 레지스트리 (Registry): agentos-sdk.dev/registry
• 📊 벤치마크 (Benchmarks): agentos-sdk.dev/docs/benchmarks
• 🏗️ 아키텍처 (Architecture): agentos-sdk.dev/docs/architecture
• 💬 Discord: rivet.dev/discord

요약 (Summary)

agentOS는 다음과 같은 구체적인 엔지니어링 질문에 답합니다: "내 제품에서 AI 에이전트를 실행하고 싶지만, 샌드박스의 콜드 스타트 (cold start) 지연 시간, 높은 메모리 오버헤드 (memory overhead), 그리고 분당 과금 방식을 수용하고 싶지는 않다." 그 해답은 V8 격리 (isolates) + WebAssembly (Wasm)를 사용하여 충분히 괜찮은 VM을 구현하고, 이를 npm 라이브러리로 패키징하여 개발자들이 자신의 백엔드에 직접 npm install 할 수 있도록 하는 것입니다.

기억할 만한 세 가지 설계 결정 사항:

바인딩 (Bindings)이 핵심 통찰입니다: "에이전트가 당신의 HTTP API를 호출하는 것"이 아니라, "에이전트가 VM 내부에서 CLI 명령어로 노출된, 당신이 정의한 TypeScript 함수를 호출하는 것"입니다. 자격 증명 (Credentials)은 VM에 절대 들어가지 않으며, 지연 시간은 거의 제로에 가깝고, 에이전트의 기능 범위 (capability surface)는 전적으로 당신의 통제하에 있습니다.

성능 격차는 최적화의 문제가 아니라 구조적인 문제입니다: 전체 샌드박스의 최소 인스턴스는 1 vCPU + 1 GiB입니다. 무엇을 실행하든 이 최소 비용을 지불해야 합니다. 반면 V8 격리 (isolate)의 최소 비용은 수십 메가바이트 수준입니다. 이것은 영리한 최적화로 만들어진 격차가 아니라, 서로 다른 격리 계층 (isolation layer)을 선택한 결과입니다.

완전한 샌드박스 (sandbox)를 대체하는 것이 아니라 보완하는 방식: sandbox mounting 기능은 개발팀이 agentOS의 경계를 정확히 이해하고 있음을 보여줍니다. 워크로드에 진정으로 실제 Linux 환경이 필요한 경우, WebAssembly에서 전체 OS를 에뮬레이션하려고 시도하는 대신 샌드박스의 파일 시스템을 VM (가상 머신)에 마운트하십시오.

AI 에이전트 기능이 필요하지만 샌드박스 서비스 비용과 지연 시간 (latency)에 만족하지 못하는 제품을 구축하고 있다면, npm install @rivet-dev/agentos를 진지하게 검토해 볼 가치가 있습니다.

실제 기업 워크플로우를 통해 검증된 AI 에이전트 및 기술의 큐레이션 마켓플레이스인 PrimeSkills를 탐색해 보세요. 과장 없이, 실제로 작동하는 것들만 제공합니다.

더 많은 통찰력과 흥미로운 제품을 확인하려면 저의 개인 사이트를 방문해 주세요.