flar

FLAR은 Fast Light Agent Restrictor입니다. 이는 gars라는 바위 위에서 동작합니다.

Go로 작성된 간단하고 가벼운 CLI 도구로, Claude Code, Antigravity, Codex, Copilot, Reasonix와 같은 코딩 에이전트 CLI를 격리된 Bubblewrap (bwrap) 샌드박스 안에서 안전하게 실행합니다.

목적은 복잡한 설정 없이 즉시 AI 에이전트를 bubblewrap하여 현재 작업 중인 프로젝트에만 접근할 수 있도록 제한하는 것입니다. 이는 프롬프트 인젝션 공격과 에이전트가 충분한 검증 없이(혹은 단순히 운이 나빠서) 프로젝트로 가져올 수 있는 라이브러리의 공급망 문제로부터 보호합니다. 접근 가능한 민감 정보는 에이전트 자체의 인증 정보와 해당 프로젝트의 대화 기록뿐입니다.

대부분의 에이전트는 "샌드박스" 기능을 제공하지만, 이는 상당히 취약하며 에이전트 스스로 접근 범위를 확장할 수 있습니다. 그리고 당연히 공급망 취약점은 에이전트 샌드박스의 영향을 받지 않습니다. flar는 에이전트로부터 완전히 차단되어 있으며, 공급망 공격의 피해 범위를 엄격하게 제한합니다.

Bubblewrap은 매우 철저히 테스트되었고 적극적으로 유지 관리됩니다. Flatpack과 다른 많은 프로젝트에서 경량 컨테이너로 사용됩니다. flar는 훨씬 덜 테스트되었으며, 제가 며칠 동안 사용하고 있습니다.

기능

• Bubblewrap 샌드박스: 깨끗한 루트 디렉토리(tmpfs)를 사용하여 비특권 사용자 네임스페이스에서 에이전트를 실행합니다. 시스템 경로(/usr, /bin, /lib, /lib64 등)는 호스트에서 읽기 전용으로 마운트되어 컨테이너 이미지 관리 없이 호스트 패키지를 즉시 사용할 수 있습니다.
• 엄격한 파일시스템 격리: 대상 프로젝트 디렉토리만 읽기-쓰기로 바인드 마운트됩니다. 호스트 홈 디렉토리의 나머지 부분은 숨겨져 SSH 키, 셸 설정, 개인 파일을 프롬프트 인젝션 공격으로부터 보호합니다.
• 네트워크 샌드박싱:
  • 격리 모드 (기본값): 네트워크 네임스페이스가 분리됩니다. 인터넷 접속은 호스트 측 HTTP/HTTPS 프록시를 통해 터널링되며, 이 프록시는 호스트에서 DNS 조회를 수행하고 로컬/루프백 IP 주소로의 트래픽을 필터링합니다.
  • 포트 포워딩: 특정 포트를 호스트의 localhost에 매핑하여 로컬 서비스(예: 데이터베이스, llama.cpp 모델)를 샌드박스 안으로 선택적으로 노출합니다.
  • 호스트 모드: 제한 없는 접근을 위해 호스트의 네트워크 네임스페이스를 공유하는 옵션입니다.
• 위험한 우회 옵션: 에이전트가 런타임 승인 중단 없이 실행되도록 플래그(Claude/agy의 경우 --dangerously-skip-permissions, Codex의 경우 --dangerously-bypass-approvals-and-sandbox)를 자동으로 주입합니다. -ask 플래그로 비활성화할 수 있습니다.
• 설정 복사: 호스트 인증 정보(예: ~/.claude/, ~/.codex/, ~/.gemini/ 또는 GitHub CLI 설정)를 샌드박스 홈 디렉토리 내부에 마운트된 임시 디렉토리로 자동 복사하며, 호스트 설정 파일은 그대로 둡니다.
• 세션 지속성 및 재개: 안전한 경우(현재 Claude Code 및 Reasonix) 샌드박스 내에서 시작된 대화는 호스트에 다시 기록되므로 --resume/--continue가 실행 간에 작동합니다. 이때 현재 프로젝트로 범위가 제한되어 다른 프로젝트의 기록이 샌드박스로 들어가지 않습니다. 그 외의 경우, 특정 에이전트와 프로젝트에 대해 flar를 처음 실행할 때 기록이 분기(fork)됩니다. 세션 지속성 및 재개 참조.
• 키링 브리징 (agy): Antigravity CLI는 OAuth 토큰을 파일이 아닌 OS 키링에 저장합니다. flar는 해당 비밀 하나만 추출하여 개별적인 인-프로세스 Secret Service를 통해 샌드박스 내부에서 제공하므로, 에이전트는 키링의 나머지 부분을 노출하지 않고 인증합니다. 인증 정보 참조.

빌드 및 설치

의존성

호스트 시스템에 bwrap (Bubblewrap)이 설치되어 있는지 확인하세요:

# Fedora/RHEL
sudo dnf install bubblewrap

# Debian/Ubuntu
sudo apt install bubblewrap

컴파일 및 설치

소스에서 flar를 빌드하려면:

go build -o `flar` .

설치하려면:

mv `flar` ~/.local/bin/

사용법

프로젝트 폴더에서 flar를 실행하거나 경로를 지정하세요:

flar [flags] [path/to/project] [extra agent args/prompts...]

플래그

• -m: 실행할 에이전트를 지정합니다 (claude, codex, agy, copilot, reasonix). 기본값은 사용 가능한 호스트 설정 또는 환경 변수를 확인합니다.
• -ask: 권한/승인을 건너뛰지 않도록 합니다 (에이전트가 권한을 묻도록 강제).
• -network: 네트워크 모드: isolated (기본값) 또는 host.
• -allow-port: 격리된 네트워크 샌드박스를 통해 특정 로컬 TCP 포트(예: 8080, 11434)를 허용합니다. 여러 번 지정할 수 있습니다.
• -v: 상세 로깅을 활성화합니다.

설정 파일 (.flar.json)

<project>/.flar.json에 프로젝트별 옵션을 구성하거나 ~/.config/flar/config.json에 전역 옵션을 구성할 수 있습니다:

{
  "agent": "claude",
  "ask": false,
  "network": "isolated",
  "allow_ports": [5432, 11434]
}

인증 정보

설정의 임시 복사본만 마운트되므로 에이전트는 원본을 건드리지 않고 기존 호스트 세션을 사용하여 인증된 상태로 실행됩니다. 대부분의 에이전트는 세션을 파일에 저장하며 flar가 이를 직접 복사합니다:

• Claude: ~/.claude/ (.credentials.json 포함) 그리고 ~/.claude.json (온보딩 상태와 계정 ID를 보유한 최상위 파일). 둘 다 필요합니다. 자격 증명만 있으면 Claude는 샌드박스를 새 설치로 간주하고 로그인을 요구합니다.
• Codex / Copilot: ~/.codex/, ~/.copilot/, 그리고 GitHub CLI 설정.

Antigravity (agy) 키링

agy는 예외입니다: 토큰을 파일에 저장하지 않습니다. OS 키링에 보관하며, D-Bus 세션 버스를 통해 freedesktop Secret Service API로 읽습니다. 샌드박스에는 세션 버스가 없으므로, 순진한 설정은 authentication failed or timed out 오류와 함께 실패합니다.

flar는 이를 특별히 처리합니다:

1. 호스트에서 secret-tool을 사용하여 오직 agy 토큰(키링 항목 service=gemini, username=antigravity)만 추출하고, 임시 설정 디렉토리에 0600 권한의 파일로 기록합니다.
2. 샌드박스 내부에서는 개인 Unix 소켓에서 최소한의 자체 포함 Secret Service (flar --internal-secretsvc)를 실행하며, DBUS_SESSION_BUS_ADDRESS로 지정됩니다. 이 서비스는 해당 단일 토큰만 제공하고 그 외에는 아무것도 제공하지 않습니다.

에이전트는 정확히 자신의 토큰에만 접근할 수 있습니다. 키링의 나머지 부분(브라우저 비밀번호, 다른 앱의 비밀 등)에는 접근할 수 없습니다. 구현은 D-Bus 와이어 프로토콜을 직접 사용하므로 샌드박스 내부에 gnome-keyring 또는 dbus-daemon이 필요하지 않습니다.

요구 사항 및 주의사항:

• 호스트 측 추출을 위해 호스트에 secret-tool (libsecret)이 설치되어 있어야 합니다. 없거나 토큰을 찾을 수 없으면 flar는 브리지를 건너뛰고 agy는 일반 로그인 프롬프트로 대체됩니다.
• 정의상 인증된 모든 에이전트는 자신의 토큰을 읽을 수 있습니다. 프롬프트 인젝션 공격은 이를 유출할 수 있습니다. 이는 인증된 상태로 실행하는 데 내재된 문제입니다. 키링 브리지는 전체 키링이 아닌 해당 하나의 토큰으로 노출을 제한합니다.

세션 지속성 및 재개

샌드박스는 설정의 임시 복사본을 마운트하므로, 에이전트가 그곳에 쓰는 모든 것(방금 한 대화 포함)은 일반적으로 종료 시 사라집니다. flar는 각 에이전트의 대화 기록 저장소를 호스트에 다시 바인드하여 세션이 지속되고 나중에 재개될 수 있도록 하면서, 다른 프로젝트의 기록이 샌드박스로 들어가지 않도록 합니다.

• Claude: 대화 기록은 프로젝트별 디렉토리(~/.claude/projects/<project-slug>/)에 저장됩니다. flar는 복사된 설정 위에 현재 프로젝트의 디렉토리만 호스트에서 바인드하므로 claude --resume은 이 프로젝트의 세션만 볼 수 있습니다. 주의: 기록에 저장된 프롬프트 인젝션이 여전히 위험할 수 있습니다. 작업 중인 프롬프트 인젝션이 포함된 세션을 재개하면 flar 외부에서 claude를 실행할 때 피해 범위가 무한히 커집니다. 편의성이 위험보다 크다고 생각합니다. 그러한 위험이 있는 프로젝트의 경우 항상 flar 안에서 실행하십시오.

• Codex CLI: Codex는 대화 기록을 ~/.codex/sessions/의 날짜 기반 디렉토리에 저장하고 전역 state_5.sqlite에 인덱싱합니다. 두 곳 모두 각 스레드의 cwd를 기록하지만, 디스크 상의 디렉토리는 프로젝트를 혼합합니다. flar는 각 작업 공간에 $XDG_STATE_HOME/flar/codex/<project-slug>/ 아래에 그림자 Codex 홈을 부여하며, 해당 변수가 설정되지 않은 경우 ~/.local/state/flar/codex/<project-slug>/로 대체됩니다. 처음 사용 시 일치하는 대화 파일, SQLite 행, 프롬프트 기록 항목만으로 해당 홈을 초기화합니다. 그런 다음 그림자 홈이 로 마운트되므로 새 세션이 지속되면서 로 다른 프로젝트가 노출되지 않습니다.

~/.copilot/.flar/<project-slug>/

처음 사용 시 flar는 해당 작업 공간의 cwd와 일치하는 세션만 그림자 홈에 초기화하며, 관련 SQLite 행과 일치하는 session-state/ 디렉토리를 모두 복사합니다. 이후 전체 그림자 홈이 샌드박스 내부에서 ~/.copilot으로 바인드 마운트되므로 copilot --continue는 이 작업 공간의 세션만 재개할 수 있고, 새 세션은 안전하게 지속됩니다.

• Antigravity (agy): Copilot과 마찬가지로, flar에 의해 프로젝트에서 처음 실행될 때 세션이 "분기"되며, 더 이상 flar 외부에서 실행되는 agy와 공유되지 않습니다.

agy는 디스크에서 대화를 프로젝트별로 구분하지 않습니다. 모든 프로젝트의 모든 대화는 ~/.gemini/antigravity-cli/ 아래 하나의 플랫 저장소(conversations/, brain/, implicit/)에 UUID로만 키가 지정되어 있으며, 소유 작업 공간은 불투명한 대화 blob 내부에 기록됩니다. 최근성 인덱스(cache/last_conversations.json)는 각 작업 공간을 가장 최근 대화에 매핑하며, 이것이 agy --continue가 따르는 정보입니다.

이 저장소를 그대로 샌드박스에 바인드하면 샌드박스된 agy가 --continue, 대화형 선택기, 또는 명시적 --conversation <ID>를 통해 다른 프로젝트에 속한 대화를 재개하여 그 안에 붙여넣은 내용을 유출할 수 있습니다. 이를 방지하기 위해 flar는 각 작업 공간에 범위가 지정된 저장소를 부여합니다:

~/.gemini/antigravity-cli/.flar/<project-slug>/

이 디렉토리는 샌드박스 내부에서 conversations/, brain/, implicit/, history.jsonl, cache/last_conversations.json 위에 바인드 마운트됩니다. 따라서 프로젝트 A에서 열린 샌드박스는 오직 프로젝트 A의 대화만 볼 수 있습니다. 새 세션은 범위 저장소에 축적되며 다음 실행 시 재개 가능합니다.

flar가 프로젝트에서 agy를 처음 실행할 때, 기존 호스트 기록에서 해당 프로젝트의 범위 저장소를 초기화합니다. 단, agy 자체가 이 작업 공간에 속한다고 판단한 대화만(평문 last_conversations.json과 history.jsonl로 결정하며, 대화 blob을 파싱하지 않음) 가져옵니다. 이 일회성 초기화 후 범위 저장소는 독립적입니다: 새 세션은 범위 저장소에만 저장되며, 이후 호스트 측 변경 사항은 가져오지 않습니다.

• Reasonix: Claude Code와 동일합니다. Reasonix는 각 프로젝트 기록을 자체 하위 디렉토리에 보관하므로, Claude Code와 같은 방식으로 바인드 마운트할 수 있으며 동일한 주의사항이 적용됩니다.

주의해야 할 결과:

• Copilot CLI: agy와 마찬가지로, 초기 초기화 후 범위가 지정된 그림자 홈은 별도의 프로젝트별 세계가 됩니다. flar 외부에서 Copilot으로 시작한 세션은 나중에 flar 안으로 가져오지 않으며, flar 내부에서 시작한 세션은 호스트의 전역 Copilot 저장소가 아닌 범위 그림자 홈에 저장됩니다.
• flar 외부에서 agy로 시작한 세션은 (초기 초기화를 제외하고) flar 내부에서 볼 수 없으며, 그 반대도 마찬가지입니다. 이는 의도적인 것입니다. flar의 agy 기록은 별도의 프로젝트별 세계입니다.
• Codex도 동일한 규칙을 따릅니다: 일회성 초기화 후, 래핑된 Codex와 래핑되지 않은 Codex의 기록은 독립적입니다.
• agy의 자체 인덱스가 현재 작업 공간에 귀속시키지 않은 대화는 설계상 초기화되지 않습니다. 다른 프로젝트의 데이터를 노출할 위험보다는 보류하는 것이 안전한 기본값입니다.
• 에이전트 소유의 .flar/ 디렉토리는 호환성을 위해 설정 복사에서 제외되며, flar 소유 상태는 $XDG_STATE_HOME/flar/ (또는 ~/.local/state/flar/) 아래에 있으며, 에이전트가 관리하는 설정 디렉토리 외부에 있습니다.

네트워크 보안 및 로컬 포트

격리 네트워크 모드에서 에이전트의 환경은 호스트 네트워크 인터페이스에 직접 접근할 수 없습니다.

• 인터넷 접속: HTTP_PROXY 및 HTTPS_PROXY 환경 변수를 사용하여 HTTP/HTTPS 요청(예: Anthropic이나 Gemini와 같은 클라우드 LLM 연결)에 대해 자동으로 작동합니다.
• Localhost 제한: 프록시를 통한 localhost 또는 루프백 IP로의 요청은 차단됩니다.
• 로컬 서비스 노출: 에이전트가 로컬 데이터베이스 또는 로컬 LLM(예: 127.0.0.1:11434의 Ollama)에 도달할 수 있도록 하려면 -allow-port 11434 또는 allow_ports 설정을 사용하여 포트를 지정하세요. 보안 루프백 포워더가 샌드박스 내부에서 127.0.0.1:11434를 바인드하고 트래픽을 호스트로 프록시합니다.