Copy-on-Write 오버레이

AgentFS는 오버레이 파일시스템으로 copy-on-write 격리를 제공해요. 덕분에 에이전트가 마음껏 파일을 수정하면서도 원본 데이터는 안전하게 지켜져요.

출처: 문서

본문

오버레이 작동 방식

오버레이 파일시스템은 두 개의 레이어를 결합해요:

┌────────────────────────────────────┐
│         Merged View (what you see) │
├────────────────────────────────────┤
│  Delta Layer (AgentFS database)    │  ← Writes go here
├────────────────────────────────────┤
│  Base Layer (original directory)   │  ← Read-only
└────────────────────────────────────┘

파일 읽기:

1. 먼저 델타 레이어를 확인해요
2. 없으면 베이스 레이어에서 읽어요

파일 쓰기:

1. (베이스에서 온 파일이면) 파일을 델타 레이어로 복사해요
2. 변경 내용을 델타 레이어에 기록해요
3. 베이스 레이어는 절대 수정되지 않아요

파일 삭제:

1. 델타 레이어에 "whiteout" 마커를 만들어요
2. 병합 뷰에서는 파일이 삭제된 것처럼 보여요
3. 베이스 레이어의 원본 파일은 그대로예요

오버레이 파일시스템 만들기

agentfs run으로 만들기

가장 간단한 방법으로, 현재 디렉터리 위에 오버레이를 자동으로 만들어요:

cd /path/to/project
agentfs run /bin/bash

agentfs init --base로 만들기

오버레이를 명시적으로 만들기:

agentfs init my-overlay --base /path/to/project

그다음 마운트하기:

agentfs mount my-overlay ./workspace

또는 그 안에서 명령 실행하기:

agentfs run --session my-overlay /bin/bash

변경 내역 보기

베이스와 무엇이 다른지 확인하기:

agentfs diff my-overlay

실전 예제

안전한 리팩토링

에이전트가 위험 없이 코드를 리팩토링하게 하기:

cd my-project
agentfs run --session refactor python3 refactor_agent.py

# Review what changed
agentfs diff refactor

# Happy? Apply changes manually or via script
# Not happy? Just delete the session
rm .agentfs/refactor.db

파괴적 작업 테스트

위험한 작업도 안전하게 시도해 볼 수 있어요:

agentfs run --session test /bin/bash
$ rm -rf src/  # Yikes!
$ exit

# Original files are fine
ls src/  # Still there!

# Only the overlay was affected
agentfs fs ls test  # Shows the deletion

병렬 실험

같은 코드베이스에서 여러 실험을 동시에 돌리기:

# Experiment A
agentfs run --session exp-a python3 approach_a.py

# Experiment B (same base, different changes)
agentfs run --session exp-b python3 approach_b.py

# Compare results
agentfs diff exp-a
agentfs diff exp-b

저장 효율성

오버레이는 다음만 저장해요:

• 수정된 파일 - 첫 쓰기 이후 전체 복사본
• 새 파일 - 델타에 전체 저장
• 삭제된 파일 - 작은 whiteout 마커

원본 파일은 절대 복제되지 않아요. 1MB 변경이 있는 10GB 프로젝트는 델타 레이어에 약 1MB만 사용해요.

기술 세부 사항

파일 작업

Whiteout

베이스 파일을 삭제하면 AgentFS는 파일을 가리는 "whiteout" 마커를 만들어요:

-- Whiteouts in the database
SELECT * FROM fs_inode WHERE whiteout = 1;

데이터베이스 스키마

델타 레이어는 SQLite에 저장돼요:

-- Files and directories
CREATE TABLE fs_inode (
    ino INTEGER PRIMARY KEY,
    parent_ino INTEGER,
    name TEXT,
    mode INTEGER,
    size INTEGER,
    ...
    whiteout INTEGER DEFAULT 0
);

-- File contents
CREATE TABLE fs_block (
    ino INTEGER,
    block_num INTEGER,
    data BLOB
);

전체 스키마는 AgentFS Specification에서 확인할 수 있어요.

더 알아보기 (Learn more)

• 세션 — 에이전트 간 상태 공유하기
• 동기화 — 오버레이를 Turso Cloud에 동기화하기
• 변경 감사 — diff와 타임라인으로 에이전트 작업 검토하기
• AgentFS 소개 — AgentFS 개념 살펴보기