aicontainer
npm version
release
rebuild
License: MIT
Container: GHCR
Devcontainer spec
여러 프로젝트에서 [Claude Code], [Codex], 그리고 [OpenCode]를 위한 샌드박스(sandboxed) devcontainer입니다.
바이패스(bypass)/자동 승인(auto-approve) 모드를 지원합니다.
왜 필요한가요? 이 CLI(Command Line Interface)들은 자동 승인(auto-approve)이 켜져 있을 때 가장 잘 작동합니다. 하지만 실제 $HOME 환경에서는 프롬프트에 주입된 의존성(dependency)이 .env 파일을 읽거나, 쉘 히스토리(shell history)를 복사하거나, gh 토큰을 사용하여 푸시할 수 있습니다. aicontainer는 AI를 devcontainer 경계 안에 배치합니다. 사용자는 자동 승인을 유지하면서도 매번 사고가 발생할 때마다 자신들의 머신을 재구축할 필요가 없습니다.
기능 (Features)
-
파일 시스템 격리(Filesystem isolation). 프로젝트 디렉터리만이 유일하게 쓰기 가능한 호스트 경로입니다. 사용자의 홈(~), ~/.ssh, 그리고 SSH 에이전트는 컨테이너 내부에 포함되지 않습니다.
-
기본적으로 Docker 객체 접근 차단. digest-pinned [socket proxy]를 사용하여 ping과 version만 허용합니다. 읽기 또는 쓰기 액세스는 명시적인 옵트인(opt-in)이 필요합니다.
-
정제된 호스트 설정(Sanitized host config). 호스트 Git 및 도구 환경 설정은 네트워크 연결이 없는(networkless) 정제기(sanitizer)를 통과합니다. 에이전트는 허용 목록에 있는 필드만 받습니다. 자격 증명(Credentials), 훅(hooks), statusLine, 그리고 Git 자격 증명 도우미(credential helpers), 별칭(aliases), 및 포함 항목은 제거됩니다.
-
단 한 번의 로그인. 네트워크 연결이 없는 자격 증명 브릿지(credential bridge)는 프로젝트 간에 로그인 토큰만 공유합니다. 전사(Transcripts), 메모리, 설정은 프로젝트별로 유지됩니다.
-
시작 전 유효성 검사(Validated before start). aic는 Docker가 어떤 작업을 시작하기 전에 관리되는 파일과 완전히 해결된 Compose 모델을 확인합니다.
-
네트워크 제어(Network controls). 클라우드 메타데이터(Cloud-metadata)와 링크 로컬 주소(link-local addresses)는 항상 차단됩니다. 아웃바운드 허용 목록은 옵트인으로 사용할 수 있습니다.
-
공유 가드레일 후크(Shared guardrail hook). 세 가지 도구 모두에서 명백한 .env 읽기, curl | sh 실행, 샌드박스 제어 파일 쓰기를 거부하는 하나의 PreToolUse 후크가 있습니다.
Trail of Bits devcontainer와 유사하며, Codex와 OpenCode가 추가되었고, 세 가지 명시적인 Docker 접근 모드, 그리고 root 관리 셸 및 설정 시작 기능을 제공합니다.
빠른 시작(Quick start)
다음이 필요합니다: Compose 2.35+가 포함된 Docker Engine 25 이상 (Docker Desktop, OrbStack, Colima, Rancher Desktop, rootful Lima 또는 rootless Docker), Node.js 18 이상, 그리고 Git 체크아웃입니다. 자세한 내용은 Install을 참조하세요.
-
CLI 설치:
npm install -g aicontainer
aic doctor # 선택 사항: 호스트 확인
2. 스크래치 프로젝트에서 한 번 로그인합니다. 이 단계 이후 모든 프로젝트에서 로그인이 작동합니다:
```bash
mkdir -p ~/sandbox/scratch && cd ~/sandbox/scratch && git init
aic init && aic up && aic shell
...
-
프로젝트에서 사용하기:
cd my-project
aic init # 작은 관리형 .devcontainer/ 파일을 작성합니다.
aic up # 설정을 검증한 다음, 샌드박스를 시작합니다.
...
VS Code에서는 `aic init`을 한 번 실행한 다음, **Dev Containers: Reopen in Container**를 사용하세요. [Usage](docs/user/usage.md)를 참조하세요.
> **경고:** 알 수 없는 저장소의 `.devcontainer/`을 **Reopen in Container**로 직접 열지 마세요. VS Code는 aic이 검증하기 전에 호스트 측 명령을 실행합니다. `aic init --force`를 실행하고, diff를 검토한 다음, `aic up`을 실행하세요.
## 경계를 넘나드는 것(What crosses the boundary)
| 표면 (Surface) | 컨테이너 내부 여부? (In the container?) |
|---|---|
| 프로젝트 디렉터리 (Project directory) | **예, 읽기/쓰기**, `/workspace`에서. `.devcontainer/` 및 Git 제어 파일은 읽기 전용입니다. |
| ... |
실제 프로젝트에 대해 이것을 출력하려면 `aic preflight`를 실행하세요. 전체 표와 위협 모델은 [Security](docs/user/security.md)에 있습니다.
## 문서(Documentation)
[documentation index](docs/README.md)에는 전체 사용자 가이드와 기여자 가이드가 있습니다. 일반적인 페이지:
- [설치](docs/user/install.md) — 전제 조건(prerequisites), 설치, 첫 로그인(first login), 제거(uninstall).
- [사용법](docs/user/usage.md) — 명령어(commands), 진단 도구(diagnostics), 도구(tools), 셸(shells), VS Code, Claude Code 플러그인.
- [사용자 정의](docs/user/customization.md) — `aic sync`을 거쳐도 유지되는 프로젝트 소유 오버라이드(project-owned overrides).
- [스택 참조](docs/user/stack-reference.md) — 각 스택에 대한 프로젝트 소유 파일과 복사 가능한 코드 조각(copy-ready snippets).
- [추가 도구 설치](docs/user/extra-tools.md) — `Dockerfile.project`와 Playwright 레시피.
- [업데이트](docs/user/updating.md) — AI 도구 및 aicontainer 업데이트.
- [보안](docs/user/security.md) — 경계를 넘나드는 것과 위협 모델(threat model).
- [문제 해결](docs/user/troubleshooting.md) — FAQ 및 알려진 문제점.
- [안정성 계약](docs/user/stability.md) — aicontainer를 기반으로 구축된 도구가 릴리스 전반에 걸쳐 의존할 수 있는 것.
## 기여 및 보안 (Contributing and security)
버그, 아이디어, 풀 리퀘스트(pull request)를 환영합니다. 먼저 [CONTRIBUTING.md](CONTRIBUTING.md)를 읽어보세요: 기본 규칙, 개발 루프(development loop), 그리고 우리가 병합하지 않는 것들. 참여함으로써, 당신은 [행동 강령(Code of Conduct)](CODE_OF_CONDUCT.md)에 동의합니다.
보안 취약점 발견 시 공개 이슈를 열지 마십시오. [비공개 보안 자문 흐름(private security advisory flow)]을 사용하십시오.
## 라이선스 (License)
[MIT](./LICENSE) © 2026 Stefano Ginella
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38