Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Eclipse Enclave는 Docker 기반 샌드박스를 활용하여 Claude, Codex 등 에이전트 코딩 도구를 격리된 컨테이너에서 안전하게 실행할 수 있게 합니다. 이 시스템은 호스트 프로젝트 파일의 안전성을 보장하며, 네트워크 접근을 허용 목록으로 제한하고 세션 정보를 지속적으로 관리합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기A Docker 기반 샌드박스를 이용하여 Claude, Codex, OpenCode 및 기타 에이전트 코딩 도구를 격리된 컨테이너에서 실행할 수 있으며, 이 과정에서 호스트의 프로젝트 파일은 안전하게 유지됩니다. 기본적으로 네트워크 접근은 허용 목록(allowlisted) 도메인으로 제한되며, 인증 정보와 기록은 세션 간에 지속되고, YOLO 모드가 활성화되어 에이전트가 확인 프롬프트 없이 행동할 수 있습니다.
<a href="https://enclave.eclipse.dev">웹사이트</a> · <a href="https://enclave.eclipse.dev/docs/getting-started">시작하기</a> · <a href="https://enclave.eclipse.dev/docs">문서</a>
Linux와 macOS(Docker Desktop 사용 시)는 네이티브로 지원됩니다. Windows의 경우, Enclave가 WSL2 내부에서 실행됩니다: Linux 명령어는 WSL 배포판 내에서 적용되며, enclave.exe는 네이티브 빌드가 아닌 이를 포워딩하는 런처입니다. Windows를 참조하십시오.
런타임 종속성:
PATH에 있고 데몬이 실행 중인 상태)와 buildx 플러그인이 필요합니다. 샌드박스 이미지 빌드는 BuildKit을 요구합니다. Rootless Docker는 지원되지 않습니다.podman이 PATH에 있고 rootless로 작동하는 경우). Enclave는 설치된 엔진을 감지하며, 둘 다 있는 경우에는 한 번 질문합니다: 백엔드 감지 및 Podman 백엔드를 참조하십시오.qemu 백엔드를 위한 qemu-system-x86_64와 cpio가 있습니다. 이는 x86-64 게스트를 빌드하며, KVM을 통해 가속할 수 있는 x86-64 Linux 호스트에서만 실용적입니다. arm64 호스트 및 macOS에서는 전체 에뮬레이션으로 폴백(fallback)됩니다. 기본 docker 백엔드는 영향을 받지 않으며 모든 지원 플랫폼에서 네이티브로 실행됩니다.소스에서 빌드하려면 Make와 Go 1.24 이상이 추가로 필요합니다. 배포판에서 충분히 최신 버전을 제공하지 않는 경우 공식 Go 설치 지침을 사용하십시오.
Ubuntu 24.04에서는 다음 명령어로 런타임 종속성을 설치합니다:
sudo apt-get update
sudo apt-get install docker.io docker-buildx git
sudo systemctl enable --now docker
Fedora 44에서는 다음 명령어로 런타임 종속성을 설치합니다:
sudo dnf install docker docker-buildx
sudo systemctl enable --now docker
Docker 소켓에 대한 접근이 필요합니다. 두 배포판 모두에서 docker 그룹을 사용하려면 사용자 계정을 추가한 후 로그아웃했다가 다시 로그인하거나, 현재 터미널에서 멤버십을 적용하기 위해 newgrp docker를 실행하십시오:
sudo gpasswd -a "$USER" docker
Docker의 Linux 사후 설치 지침을 참조하고 그룹이 가진 root에 상응하는 권한을 고려하십시오.
enclave를 일반 사용자로 실행해야 하며, sudo를 통해 실행해서는 안 됩니다. enclave는 --allow-root 플래그를 전달하거나 ENCLAVE_ALLOW_ROOT=1로 설정하지 않는 한 root로 실행하기를 거부합니다 ( root로 실행 참조). 또한 프로젝트 디렉토리에서 실행해야 합니다. --allow-sensitive-mounts 플래그를 전달하지 않으면 홈 디렉토리, ~/.ssh와 같은 숨겨진 홈 항목 또는 기타 민감한 호스트 데이터 마운트를 거부합니다 ( 민감한 마운트 참조).
macOS에서는 Docker Desktop과 위의 소스 빌드 종속성을 설치하십시오.
x86-64용 Ubuntu 24.04의 경우, rolling release에서 .deb 파일을 다운로드한 다음, APT를 사용하여 설치하여 런타임 종속성이 해결되도록 하십시오:
sudo apt install ./enclave_*_amd64.deb
x86-64용 Fedora Linux의 경우, rolling release에서 .rpm 파일을 다운로드한 다음, DNF를 사용하여 설치하십시오:
롤링 릴리스(rolling release)는 또한 자체 포함된 바이너리를 제공합니다:
| 아티팩트 (Artifact) | 플랫폼 (Platform) |
|---|---|
enclave-linux-amd64 | Linux x86-64 |
| ... | |
다운로드한 아티팩트를 checksums.txt와 함께 사용하여, 소유하고 있는 PATH 경로의 디렉터리에 설치하여 스스로 업데이트할 수 있도록 합니다. Linux에서는: |
sha256sum --check --ignore-missing checksums.txt
install -d ~/.local/bin
install enclave-linux-amd64 ~/.local/bin/enclave
macOS에서는, Intel용으로 enclave-darwin-amd64를 대체하여 사용합니다:
shasum -a 256 --check --ignore-missing checksums.txt
xattr -d com.apple.quarantine ./enclave-darwin-arm64 2>/dev/null || true
install -d ~/.local/bin
...
대부분의 Linux 배포판은 ~/.local/bin을 로그인 시 존재하면 PATH에 추가합니다. macOS에서는 export PATH="$HOME/.local/bin:$PATH"를 ~/.zshrc에 추가하십시오.
이렇게 설치된 독립형 바이너리는 스스로 업데이트할 수 있습니다: enclave self-update는 실행 파일을 최신 빌드의 릴리스 채널, 즉 rolling으로 교체합니다. Enclave는 최대 24시간마다 다른 빌드를 확인하고 대화형 명령에서 이를 보고합니다. 자동으로 업데이트하려면 전역 config.json에 `
macOS 바이너리는 서명되지 않았고 notarize(공증)되지 않았기 때문에, 브라우저를 통해 다운로드된 바이너리에는 격리 속성(quarantine attribute)이 포함되어 게이트키퍼(Gatekeeper)가 실행을 거부하게 만듭니다. install 명령어는 이 속성을 전파하므로, 먼저 제거해야 합니다. curl이나 gh release download로 아티팩트를 가져오면 이를 완전히 피할 수 있으며, 이것이 위 명령어에서 해당 속성의 부재를 허용하는 이유입니다.
이 바이너리에는 Dockerfile, 확장 기능(extensions), 문서, 기타 런타임 자산들이 포함되어 있습니다. 첫 사용 시점에 자산을 추출합니다. 셸 자동 완성(Shell completion)은 절대 이를 추출하지 않으며, 다른 명령어가 먼저 수행할 때까지는 바이너리에서 도구 및 기능 이름을 읽어오지 않습니다.
저장소(repository)를 클론한 다음, 자급자족적인(self-contained) 바이너리를 빌드하고 설치합니다:
git clone https://github.com/eclipse-enclave/enclave.git
cd enclave
make install
Linux에서는 이 바이너리를 ~/.local/bin/에 설치합니다. 해당 디렉터리가 PATH에 포함되어 있는지 확인하십시오. macOS의 기본 경로는 /usr/local/bin/이며, 여기에 복사하려면 sudo나 쓰기 권한이 있는 /usr/local/bin이 필요할 수 있습니다. 목적지를 지정하려면 make install INSTALL_BIN=...을 사용하세요.
Linux에서는 셸 자동 완성도 설치합니다: bash는 ~/.local/share/bash-completion/completions/에, zsh는 ~/.local/share/zsh/site-functions/에 설치됩니다. bash의 경우 자동으로 인식되지만, zsh의 경우 ~/.zshrc 파일에서 fpath에 추가해야만 검색하며, 그 전에 어떤 명령어가 compinit을 실행하는지 확인해야 합니다:
fpath=(~/.local/share/zsh/site-functions $fpath)
oh-my-zsh나 prezto 같은 프레임워크는 자체적으로 compinit을 호출하므로, 위 줄을 해당 설정 앞에 배치하고 나머지는 그들에게 맡기십시오. 아무 곳에서도 이를 호출하지 않는 순수한 zsh 설정의 경우, fpath 줄 다음에 autoload -U compinit && compinit을 추가하십시오. 두 자동 완성 경로 모두 XDG_DATA_HOME이 설정되어 있으면 이를 준수합니다.
.deb 및 .rpm 패키지는 이러한 설정이 필요 없는 시스템 디렉터리에 자동 완성 기능을 모두 설치합니다. 또한, enclave completion <bash|zsh|fish> 명령어로 원하는 셸 스크립트를 온디맨드(on demand)로 생성할 수도 있습니다.
네이티브 Windows 빌드는 없습니다. WSL2에 Ubuntu 24.04 배포판을 설치하고, 그 안에서 Docker를 사용할 수 있도록 설정하세요. 이는 Docker Desktop의 WSL 통합 기능을 사용하거나 해당 배포판에 Docker Engine을 직접 설치하는 방법으로 할 수 있습니다. 그리고 위 리눅스 지침을 WSL 내부에서 따라 하되, 호스트 아키텍처와 일치하는 .deb 또는 리눅스 바이너리를 사용하십시오.
이렇게 하면 WSL 셸에서 Enclave를 사용하는 데 충분합니다. PowerShell에서도 사용하려면 Windows에 로쳇(launcher)도 설치해야 합니다:
scoop install https://github.com/eclipse-enclave/enclave/releases/download/rolling/enclave.json
enclave.exe는 모든 인수를 배포판 내부의 리눅스 바이너리로 전달하고 종료 코드를 반환합니다. 이는 네이티브 빌드가 아닙니다. 예시로 \wsl.localhost\Ubuntu\home\you\project와 같이 배포판 내부 디렉토리에서 실행하십시오. C:\\\Users\you\project와 같은 Windows 드라이브 경로는 기본적으로 거부됩니다. 이는 /mnt/c를 통해 접근해야 하며, 이 경우 모든 파일 액세스가 WSL 상호 운용성(interop) 계층을 통과하므로 현저히 느립니다.
작업 디렉토리 규칙, 환경 포워딩 및 종료 코드에 대한 내용은 Windows를 참조하십시오.
모든 프로젝트 디렉토리에서 실행합니다:
enclave # 현재 프로젝트의 도구 시작 (첫 실행 시 어떤 도구를 사용할지 묻습니다)
enclave --tool codex # 한 번의 실행에 다른 도구 사용
enclave --backend qemu --tool codex # 실험적인 QEMU 마이크로VM 실행 (implies --slim, all-network)
...
세션은 Git 저장소 외부에서도 구성된 Git 작성자 및 커미터(committer) 신원을 필요로 합니다. 둘 중 하나라도 불완전하면 컨테이너를 시작하기 전에 enclave가 종료됩니다. Git 신원을 참조하십시오.
도구 선택: 첫 번째 대화형 세션(interactive session)에서는 어떤 코딩 에이전트(coding agent)를 실행할지 묻고 그 답변을 ~/.config/enclave/config.json 파일의 "tool"로 저장합니다. 이후 실행부터는 질문 없이 시작됩니다. 스크립트나 비터미널 실행 시에는 절대 묻지 않습니다. 도구가 설정되어 있지 않으면 --tool과 tool 키를 언급하는 메시지와 함께 실패합니다. 도구 선택을 참조하세요.
인증(Authentication): 가장 간단하고 권장되는 접근 방식은 컨테이너 내부에서 처음 실행할 때 로그인하는 것입니다. OAuth 세션은 호스트의 영구 인증 저장소(persistent auth store)에 저장되며, 이후 모든 실행에서 자동으로 재사용됩니다. 별도의 설정이 필요하지 않습니다. 대신 선언된 환경 변수 자격 증명(declared env credentials)을 사용하려면, 이들을 ~/.local/state/enclave/secrets/global.env에 배치하십시오. 인증 및 비밀 정보를 참조하세요. 전체 명령어 및 플래그 참조는 docs/cli-reference.md를 참조하세요.
~/.config/enclave/commands/host/<name>에 실행 가능한 파일을 넣으면, 해당 파일은 호스트에서 실행되는 enclave <name> 동사(verb)가 됩니다. 이 파일에는 실행 가능 비트(executable bit)가 설정되어 있어야 합니다(chmod +x). 운영체제는 셔뱅 라인(shebang line)을 통해 인터프리터를 해결하므로, 어떤 언어든 작동합니다. 심링크(Symlinks)는 대상까지 따라가기 때문에, 실행 가능한 스크립트에 대한 링크도 명령어로 등록됩니다 (손상된 링크는 경고 메시지가 표시됨). 호스트 명령어의 심링크는 어디든 가리킬 수 있지만, 세션 명령어의 심링크는 상대적 링크여야 하며 모든 단계(hop)에 걸쳐 ~/.config/enclave/commands/session 내부에 머물러야 합니다. 그 이유는 해당 디렉토리가 컨테이너 내부의 중립 경로로 바인드 마운트(bind-mounted)되며 절대 링크 대상은 거기서 해결되지 않기 때문입니다 (절대적, 탈출형 또는 루핑 세션 심링크는 경고 메시지가 표시되고 건너뜁니다). 내장 명령어는 항상 동일한 이름의 사용자 지정 명령어보다 우선합니다.
mkdir -p ~/.config/enclave/commands/host
cat > ~/.config/enclave/commands/host/deploy <<'EOF'
#!/bin/sh
...
명령어 이름 뒤에 오는 모든 것은 스크립트에 있는 그대로 전달됩니다(플래그, --, 및 --help 포함). stdin, stdout, stderr, 그리고 종료 코드는 손대지 않고 그대로 전달됩니다. enclave 자체의 플래그는 명령어 이름 앞에 와야 하며, 호스트 명령어는 그곳에서 전역 플래그만 허용합니다(예: enclave --verbose deploy). 호스트 명령어는 상속된 환경 변수에 더하여 ENCLAVE_BIN(enclave 바이너리 경로), ENCLAVE_PROJECT_ROOT(현재 프로젝트 디렉토리), 그리고 ENCLAVE_CONFIG_DIR(~/.config/enclave)를 가지고 실행됩니다.