strukto-ai/mirage

Mirage는 AI 에이전트를 위한 가상 터미널입니다. 가상 파일 시스템은 폭넓은 데이터 컨텍스트를 제공하고, 가상화된 CLI는 에이전트에게 더 유연한 도구 사용을 주며, 동적 런타임은 기반 인프라 비용을 줄이고 토큰을 더 아낍니다. 에이전트의 동작은 물론 무엇을 볼 수 있는지까지 세밀하게 제어하여 최고의 보안을 제공합니다. 이 요소들이 함께 하나의 가상화된 터미널을 이루어 최고의 에이전트 성능과 비용 효율, 보안을 제공합니다.

ws = Workspace(
    {
        "/tmp":   (RAMVFS(), MountMode.EXEC),
        "/redis": (RedisVFS(url=redis_url), MountMode.WRITE),
        "/slack": (SlackVFS(SlackConfig(token=slack_bot_token)), MountMode.EXEC),
    },
    # monty가 python을 가로채므로 스크립트는 워크스페이스 안에서 샌드박스로 실행된다
    runtimes=[MontyRuntime(captures=["python", "python3"]), "workspace"],
)

# grep 한 번으로 모든 소스를 훑는다
await ws.shell("grep -rln session /redis /tmp")

# Slack에 있는 스크립트를 실행하고 리포트를 Redis에 기록한다
await ws.shell("python3 /slack/channels/general_.../files/example__F....py > /redis/report.txt")

# 헤드 워드로 타입이 있는 CLI를 설치한다: 경로가 아니라 이름으로 디스패치되고,
# 다른 프로그램처럼 `man`, `type`, `which`로 찾을 수 있다
ws.register_cli("slack", SLACK, {"token": slack_bot_token})
await ws.shell('slack send-message --channel general --text "report is up"')

소개

• N개의 SDK와 M개의 MCP 대신 통합된 가상 터미널 인터페이스. 모든 백엔드가 동일한 파일 시스템 의미론을 사용하므로 파이프라인이 서비스 간에 조합됩니다.
• 모든 소스를 아우르는 가상 파일 시스템. S3, Google Drive, Slack, Gmail, Redis 등이 하나의 루트 아래 나란히 마운트되어, 에이전트는 이미 아는 unix 도구인 ls, grep, find, jq로 통합된 인터페이스를 통해 모두에 접근합니다.
• 가상 명령줄 도구(CLI). git, slack, ntn은 Mirage가 직접 응답하므로 에이전트는 아무것도 설치하지 않고 서로 다른 런타임과 머신에 걸쳐 서비스를 다룰 수 있고, 하나의 도구를 둘 이상으로 가상화해 각각 고유한 이름과 자격 증명을 줄 수 있습니다.
• 라우팅되는 동적 런타임. Python, JavaScript를 비롯한 모든 명령을 설정된 런타임으로, 프로세스 내부나 샌드박스 또는 원격으로 보낼 수 있어 연산과 저장소가 분리되고 한쪽을 건드리지 않고 다른 쪽을 바꿀 수 있습니다.
• 가상화된 Mirage 셸. 파일 시스템과 CLI, 런타임을 하나의 명령줄로 묶어 파이프, 리다이렉션, 변수, 잡, 히스토리가 셋 모두에서 동작합니다.
• 에이전트를 위해 설계된 프로파일. allow, ask, deny가 명령과 CLI를 통제하고 hide와 show가 파일과 폴더를 통제하므로, 숨겨진 경로는 단순히 읽을 수 없는 것이 아니라 에이전트가 보는 파일 시스템에 존재하지 않습니다.
• 스크립트로 작성하는 정책 엔진. 정책 스크립트는 위험한 동작을 실행 전에 금지할 수 있으며, 같은 스택이 모든 VFS 작업과 세션 쓰기를 통제하므로 파일도 환경 변수도 새어 나가지 않습니다.
• VFS와 에이전트에 연결된 알림. 외부 변경이 마운트의 이벤트 스트림이 되므로 새로운 Slack 답장은 가상 파일 시스템의 대화 파일 변경으로 나타나고, 에이전트는 트리를 다시 훑는 대신 그에 반응합니다.

아키텍처

설치

• Python ≥ 3.12: mirage-ai 패키지와 mirage CLI
• Node.js ≥ 20: TypeScript SDK
• macOS 또는 Linux (FUSE 기반 마운트는 플랫폼 지원 필요)

Python

uv add mirage-ai              # `mirage` 라이브러리와 `mirage` CLI 바이너리를 설치
uv add 'mirage-ai[openai]'    # OpenAI Agents 어댑터, 에이전트 프레임워크마다 별도 extra

TypeScript

npm install @struktoai/mirage-node      # Node.js 서버와 CLI
npm install @struktoai/mirage-browser   # 브라우저 / edge 런타임
npm install @struktoai/mirage-vercel    # Vercel AI 어댑터, 에이전트 프레임워크마다 별도 패키지

두 런타임 패키지 모두 @struktoai/mirage-core를 자동으로 가져옵니다.

CLI

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

빠른 시작

Python

from mirage import Workspace
from mirage.vfs.ram import RAMVFS
from mirage.vfs.s3 import S3Config, S3VFS

ws = Workspace({
    "/data": RAMVFS(),
    "/s3":   S3VFS(S3Config(bucket="my-bucket")),
})

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

await ws.snapshot("demo.tar")

TypeScript

import { Workspace, RAMVFS, S3VFS } from '@struktoai/mirage-node'

const ws = new Workspace({
  '/data': new RAMVFS(),
  '/s3':   new S3VFS({ bucket: 'my-bucket' }),
})

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

await ws.snapshot('demo.tar')

CLI

mirage workspace create ws.yaml --id demo
mirage shell --workspace_id demo --command "cp /s3/report.csv /data/report.csv"
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored

에이전트 프레임워크

Mirage는 샌드박스 또는 도구 계층으로 에이전트 프레임워크에 연결된다. read 같은 POSIX 연산도 VFS와 파일 타입별로 커스터마이즈할 수 있다: Mirage는 파일 타입 렌더러를 전혀 포함하지 않으므로 형식은 등록한 방식대로 렌더링되며, 특정 VFS와 확장자에 등록한 명령이 일반 명령보다 우선한다.

	통합
Python	OpenAI Agents SDK, LangChain, Pydantic AI, Agno
TypeScript	Vercel AI SDK, OpenAI Agents SDK, LangChain, Mastra
코딩 에이전트	Claude Code, Codex, DeepSeek Harness, Grok Build, OpenCode, Pi

캐시

모든 Workspace에는 2계층 캐시가 있어, 원격 백엔드에 대한 반복 작업이 네트워크 대신 로컬 상태를 사용합니다:

• 인덱스 캐시: 디렉터리 목록과 메타데이터. 첫 디렉터리 탐색은 API를 호출하고, 이후에는 TTL이 만료될 때까지(기본 10분) 인덱스에서 제공합니다.
• 파일 캐시: 객체 바이트. 첫 읽기는 원본에서 스트리밍하고, 이후 파이프라인은 캐시에서 읽습니다(기본 512 MB).

두 계층 모두 기본값은 설정이 필요 없는 프로세스 내 RAM입니다. Redis 스토어를 쓰면 워커, 프로세스, 머신 간에 캐시 상태를 공유합니다:

import { RedisFileCacheStore, S3VFS, Workspace } from '@struktoai/mirage-node'

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

기여자

Mirage에 기여해 주신 모든 분께 감사드립니다.