Mirage: 다양한 백엔드를 단일 트리에 마운트하는 AI 에이전트용 통합 가상 파일시스템

9bow · 5월 12, 2026, 12:30오전

Mirage 소개

LLM 기반 AI 에이전트가 다루는 백엔드의 종류는 빠르게 늘고 있습니다. S3와 GCS, Google Drive, Slack, Gmail, Notion, GitHub, Linear처럼 서로 다른 서비스가 동시에 등장하고, 각 서비스마다 SDK와 인증 방식, 페이징 규칙, 오류 처리 방식이 달라 에이전트 도구 정의와 프롬프트 자체가 점점 복잡해집니다. 또한 같은 작업이라도 LLM이 SDK 호출 코드를 새로 짜야 하는지, MCP(Model Context Protocol) 서버를 통해야 하는지에 따라 가르쳐야 하는 어휘가 달라지기 때문에, 모델을 바꾸면 에이전트의 도구 사용 능력이 함께 흔들리는 문제가 생깁니다. Mirage는 이러한 분산된 백엔드를 하나의 파일시스템으로 통합해 LLM이 이미 익숙한 Unix/bash 어휘로 모든 서비스를 다루도록 만든 가상 파일시스템(VFS, Virtual File System) 프로젝트입니다.

Mirage의 핵심 접근법은 "에이전트가 보는 시스템을 단 하나의 파일시스템으로 만든다"는 것입니다. S3 버킷은 /s3 디렉토리로, Slack 채널은 /slack 디렉토리로, GitHub 저장소는 /github 디렉토리로 마운트되며, 에이전트는 cat, grep, cp, find, wc, jq 같은 익숙한 Unix 도구로 모든 백엔드를 일관되게 다룰 수 있습니다. LLM 학습 데이터에는 이미 bash 명령과 파이프라인이 풍부하게 포함되어 있기 때문에, 새로운 SDK 어휘를 모델에게 가르칠 필요 없이 마운트 트리만 보여주면 곧바로 도구 호출이 가능합니다. 이러한 설계는 에이전트가 "한 마운트 트리 위에서 한 종류의 추론"만 수행하도록 만들어, 백엔드 종류가 늘어도 프롬프트와 도구 정의의 복잡도가 거의 늘지 않는다는 점이 차별점입니다.

기능 면에서 Mirage는 단순한 어댑터 모음을 넘어 워크스페이스(Workspace) 추상화, 두 계층 캐시(인덱스 캐시 + 파일 캐시), 스냅샷·복제·이식 기능, OpenAI Agents SDK·Vercel AI SDK·LangChain·Pydantic AI·CAMEL·OpenHands·Mastra와의 어댑터, Claude Code와 Codex 같은 코딩 에이전트와 결합하기 위한 경량 CLI/데몬까지 포함합니다. Python(mirage-ai)과 TypeScript(@struktoai/mirage-node, @struktoai/mirage-browser, @struktoai/mirage-core) SDK가 모두 제공되어 FastAPI, Express, 브라우저 앱, 엣지 런타임 등 다양한 환경에서 별도 프로세스 없이 임베드할 수 있습니다.

Mirage의 통합 가상 파일시스템 구조

Mirage의 기본 단위는 워크스페이스(Workspace)입니다. 워크스페이스는 마운트 경로와 리소스(Resource) 객체의 매핑으로 정의되며, 여기에 등록된 모든 마운트는 동일한 파일시스템 트리 아래에 노출됩니다. 다음 예시는 RAM, S3, Slack, GitHub 네 종류의 백엔드를 하나의 워크스페이스로 합친 코드입니다.

const ws = new Workspace({
  '/data':   new RAMResource(),
  '/s3':     new S3Resource({ bucket: 'logs' }),
  '/slack':  new SlackResource({}),
  '/github': new GitHubResource({}),
})

await ws.execute('grep alert /slack/general/*.json | wc -l')
await ws.execute('cat /github/mirage/README.md')
await ws.execute('cp /s3/report.csv /data/local.csv')

위 코드처럼 Mirage는 서로 다른 SaaS와 객체 저장소, 메시징 도구를 동일한 bash 파이프라인으로 다룰 수 있도록 통합합니다. 또한 Mirage는 명령 자체도 확장할 수 있는 구조이며, ws.command('summarize', ...) 처럼 워크스페이스에 새 명령을 등록하면 모든 마운트에서 사용할 수 있습니다. 특정 리소스와 파일 형식 조합에 한해서만 명령을 재정의할 수도 있어, 예를 들어 /s3 안의 Parquet 파일에 대해서만 cat이 행 단위 JSON으로 렌더링되도록 동작을 바꾸는 것도 가능합니다.

ws.command('summarize', /* ... */)

// 특정 리소스 + 파일 타입 조합에 대해서만 cat 동작을 재정의
ws.command('cat', { resource: 's3', filetype: 'parquet' }, /* ... */)

await ws.execute('summarize /github/mirage/README.md')
await ws.execute('cat /s3/events/2026-05-06.parquet | jq .user')

이 같은 명령 확장은 LLM 입장에서 별도의 새 도구 정의를 학습하지 않아도 된다는 점이 큰 장점입니다. 모델은 이미 알고 있는 cat과 summarize를 호출하기만 하면 되고, 실제로 어떤 백엔드로 라우팅되는지는 Mirage가 처리합니다.

Mirage의 아키텍처와 주요 특징

Mirage 저장소의 README는 AI 에이전트와 애플리케이션이 Mirage Bash 및 VFS 계층을 거쳐 디스패처와 캐시, 그리고 인프라/원격 백엔드와 통신하는 구조를 다이어그램으로 제시합니다. 즉, 에이전트는 마운트 트리만 보지만 그 아래에서는 실제 디스패처가 호출 의도(intent)에 맞춰 적절한 리소스 어댑터로 요청을 라우팅하며, 응답은 캐시 계층을 거쳐 사용자 측에 반환됩니다.

주요 특징은 다음과 같이 정리할 수 있습니다.

하나의 파일시스템, 모든 백엔드: RAM, 디스크, Redis, S3 / R2 / OCI / Supabase / GCS, Gmail / Google Drive / Google Docs / Sheets / Slides, GitHub / Linear / Notion / Trello, Slack / Discord / Telegram / Email, MongoDB, SSH 등 다양한 리소스를 단일 트리에 마운트합니다. 새 SDK를 외우지 않고, LLM이 가장 잘 아는 bash 어휘 위에서 추론할 수 있도록 합니다.

bash 어휘 기반의 도구 호출: 같은 LLM이 같은 도구로 모든 마운트에 접근하므로, 백엔드별 SDK나 MCP 서버를 새로 가르칠 필요가 없습니다. 모델 교체 시에도 도구 표면(surface)이 거의 동일하게 유지됩니다.

이식 가능한 워크스페이스: 워크스페이스를 복제(clone), 스냅샷(snapshot), 버전 관리할 수 있어 에이전트 실행 환경을 머신 사이에서 옮길 수 있습니다. 재구성 없이 다른 환경으로 옮겨도 동일하게 동작합니다.

SDK 임베드 친화적: Python과 TypeScript SDK 모두 비동기 런타임 안에 임베드할 수 있어, FastAPI, Express, 브라우저 앱 등 어떤 환경이든 별도 프로세스 없이 가상 파일시스템을 제공할 수 있습니다.

주요 에이전트 프레임워크 지원: OpenAI Agents SDK, Vercel AI SDK(TypeScript), LangChain, Pydantic AI, CAMEL, OpenHands, Mastra와의 어댑터를 함께 제공합니다.

경량 CLI + 데몬: Claude Code, Codex 같은 코딩 에이전트와 결합해 동일한 마운트 트리를 bash 인터페이스로 노출함으로써, 한 턴(turn) 안에 더 많은 유의미한 작업을 처리할 수 있도록 돕습니다.

Mirage의 두 계층 캐시 동작

원격 백엔드를 매번 호출하는 비용은 빠르게 누적됩니다. Mirage는 이 문제를 다루기 위해 모든 워크스페이스에 두 계층 캐시(two-layer cache)를 기본으로 적용합니다. 첫 번째 계층은 인덱스 캐시(Index cache)로, 디렉토리 목록과 메타데이터를 보관합니다. 첫 디렉토리 탐색은 원본 API를 호출하지만, 이후 동일한 탐색은 TTL이 만료될 때까지 인덱스 캐시에서 응답합니다. 두 번째 계층은 파일 캐시(File cache)로, 실제 객체 바이트를 저장합니다. 첫 읽기는 원본에서 스트리밍하지만, 이후 파이프라인은 캐시에서 즉시 응답합니다.

각 캐시 계층은 플러그형으로 설계되어 있어, 기본 RAM 캐시(인메모리, 512 MB 파일 캐시, 10분 인덱스 TTL)와 Redis 캐시(워커·프로세스·머신 사이 공유) 중에서 선택할 수 있습니다. RAM 캐시는 단일 프로세스 앱이나 노트북 실험에 적합하고, Redis 캐시는 서버리스, 다중 복제본 서비스, 재시작 후에도 캐시 상태를 유지해야 하는 환경에 적합합니다.

import { RedisFileCacheStore, RedisIndexCacheStore, Workspace } from 'mirage/node'

const ws = new Workspace(
  { '/s3': new S3Resource({ bucket: 'my-bucket' }) },
  {
    cache: new RedisFileCacheStore({ url: 'redis://localhost:6379/0', limit: '8GB' }),
    index: new RedisIndexCacheStore({ url: 'redis://localhost:6379/0', ttl: 600 }),
  },
)

캐시 동작은 README의 다음 예시처럼 인덱스/파일 별로 미스(miss)와 히트(hit)가 분리되어, 동일 디렉토리 탐색이나 동일 파일 읽기는 추가 네트워크 호출 없이 캐시에서 즉시 처리됩니다.

// 1. Index miss → S3 LIST. 인덱스 캐시에 저장.
await ws.execute('ls /s3/data/')

// 2. Index hit → 0 네트워크 호출.
await ws.execute('find /s3/data/ -name "*.jsonl"')

// 3. File miss → S3 GET. 바이트가 파일 캐시에 저장.
await ws.execute('cat /s3/data/log.jsonl | wc -l')

// 4. File hit → 0 네트워크 호출.
await ws.execute('grep alert /s3/data/log.jsonl')

Mirage의 에이전트 프레임워크 통합

Mirage는 주요 에이전트 프레임워크와 자연스럽게 결합되도록 어댑터를 제공합니다. OpenAI Agents SDK에서는 MirageSandboxClient가 Workspace를 샌드박스(sandbox)로 노출해, 에이전트가 실행하는 bash 명령이 그대로 마운트 위에서 동작합니다.

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig

from mirage.agents.openai_agents import MirageSandboxClient

client = MirageSandboxClient(ws)
agent = SandboxAgent(
    name="Mirage Sandbox Agent",
    model="gpt-5.4-nano",
    instructions=ws.file_prompt,
)

result = await Runner.run(
    agent,
    "Summarize /s3/data/report.parquet into /report.txt.",
    run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),
)

Vercel AI SDK에서는 mirageTools(ws)가 워크스페이스를 타입 지정 도구 집합으로 노출해, AI SDK에 연결된 어떤 모델이든 마운트 트리 전반에 걸쳐 읽기/쓰기를 수행할 수 있습니다.

import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { mirageTools } from '@struktoai/mirage-agents/vercel'
import { buildSystemPrompt } from '@struktoai/mirage-agents/openai'

const { text } = await generateText({
  model: openai('gpt-5.4-nano'),
  system: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),
  prompt: "Use readFile to read /docs/paper.pdf, then describe what's in it.",
  tools: mirageTools(ws),
})

LangChain, Pydantic AI, CAMEL, OpenHands, Mastra용 어댑터도 동일한 방식으로 제공되어, 에이전트 런타임이 바뀌어도 워크스페이스 정의는 그대로 사용할 수 있습니다.

Mirage 설치 및 사용법

Mirage는 Python과 TypeScript SDK, 그리고 별도의 CLI를 제공합니다. 사전 요구 사항은 Python 3.12 이상, Node.js 20 이상, 그리고 macOS 또는 Linux입니다(FUSE 기반 마운트는 플랫폼 지원이 필요합니다).

Python 사용자는 uv로 패키지를 설치할 수 있으며, mirage 라이브러리와 CLI 바이너리가 함께 설치됩니다.

uv add mirage-ai

TypeScript 사용자는 런타임에 맞는 패키지를 선택해 설치합니다.

npm install @struktoai/mirage-node      # Node.js 서버 및 CLI
npm install @struktoai/mirage-browser   # 브라우저 / 엣지 런타임
npm install @struktoai/mirage-core      # 런타임 무관 핵심 모듈

CLI는 공식 설치 스크립트로 빠르게 받을 수 있으며, 패키지 매니저로도 설치할 수 있습니다.

curl -fsSL https://strukto.ai/mirage/install.sh | sh

npm install -g @struktoai/mirage-cli
uvx mirage-ai
npx @struktoai/mirage-cli

기본 사용 흐름은 워크스페이스 정의 → 명령 실행 → 스냅샷 저장 순서입니다.

from mirage import Workspace
from mirage.resource.gdocs import GDocsConfig, GDocsResource
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource
from mirage.resource.slack import SlackConfig, SlackResource

ws = Workspace({
    "/data":  RAMResource(),
    "/s3":    S3Resource(S3Config(bucket="my-bucket")),
    "/slack": SlackResource(SlackConfig()),
    "/docs":  GDocsResource(GDocsConfig()),
})

await ws.execute("cp /s3/report.csv /data/report.csv")
await ws.execute("grep alert /s3/data/log.jsonl | wc -l")

ws.snapshot("demo.tar")

CLI를 사용한다면 워크스페이스 정의 파일(YAML)을 만든 뒤 mirage workspace 서브커맨드로 생성·실행·스냅샷·로드할 수 있습니다.

mirage workspace create ws.yaml --id demo
mirage execute   --workspace_id demo --command "cp /s3/report.csv /data/report.csv"
mirage provision --workspace_id demo --command "cat /s3/data/large.jsonl"
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored

Mirage 라이선스

Mirage는 Apache License 2.0으로 공개되어 있어 상업적/비상업적 사용 모두 허용되며, 특허 보호 조항을 포함합니다. 다만 마운트 대상이 되는 외부 서비스(S3, Slack, GitHub 등) 자체의 이용 약관은 별도로 준수해야 합니다.

Mirage 공식 홈페이지

Mirage 문서 사이트

Mirage 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~