AI 코딩 에이전트(AI coding agents)는 놀랍지만, 무언가를 rm -rf로 삭제하거나, API 키를 유출하거나, 프로젝트를 망가진 상태로 방치하기 전까지만 그렇습니다.

모든 프로젝트에는 서로 다른 도구, 자격 증명(credentials), 그리고 설정(configs)이 필요합니다. 하지만 우리 대부분은 에이전트를 호스트(host)에서 직접 실행하여, 에이전트에게 제한 없는 파일 시스템 접근 권한, 필터링되지 않은 네트워크 호출, 그리고 감사 추적(audit trail)이 없는 환경을 제공하고 있습니다.

aienv가 이 문제를 해결합니다.

github.com/kapilratnani/aienv

작동 방식

하나의 YAML 파일이 에이전트에 필요한 모든 것을 정의합니다: 실행할 바이너리(binary), 마운트(mount)할 파일, 통신 가능한 API, 그리고 주입할 환경 변수(environment variables)까지 말이죠. aienv는 해당 YAML로부터 Docker 이미지를 빌드하고, 샌드박스된 컨테이너(sandboxed container)를 실행하며, 네트워크 강제 적용을 위한 HTTP 프록시(HTTP proxy)를 구동하고, 모든 네트워크 요청을 JSONL 감사 로그(audit log)에 기록합니다.

에이전트는 **블랙박스(black boxes)**로 취급됩니다 — aienv는 사용자가 Claude Code, OpenCode, Cursor, Pi 또는 커스텀 스크립트를 실행하는지 상관하지 않습니다. CLI에서 실행될 수 있다면 무엇이든 작동합니다.

빠른 시작 (Quick Start)

설치:

go install github.com/kapilratnani/aienv@latest

환경 생성:

aienv create my-coding-env

이 과정은 대화형 설정(interactive setup)을 안내합니다. 결과물로 ~/.local/share/aienv/my-coding-env/env.yaml 위치에 YAML 파일이 생성됩니다:

env:
  name: my-coding-env
  description: coding env for my project
...

샌드박스 실행:

aienv up my-coding-env

에이전트는 격리된 Docker 컨테이너 내부에서 실행됩니다. 호스트 파일 시스템은 영향을 받지 않습니다. 종료하면 컨테이너는 제거됩니다.

에이전트 설정 및 기술 마운트 (Mount Agent Configs & Skills)

에이전트에는 설정(configs), 컨텍스트 파일(context files), 그리고 기술 디렉토리(skill directories)가 필요합니다. 기본적으로 읽기 전용(read-only)으로 마운트하고, 에이전트가 반드시 수정해야 하는 것만 쓰기 가능(writable)하게 만드세요.

agent:
  mounts:
    - source: ~/projects/my-app
...

모든 마운트(mounts)는 기본적으로 **읽기 전용 (read-only)**입니다. writable: true 플래그를 명시적으로 설정해야만 쓰기 권한을 선택적으로 사용할 수 있습니다.

환경 변수 (Environment Variables)

호스트로부터 환경 변수를 통해 비밀 값(secrets)을 전달하세요. 이미지 내에 직접 포함(baked into)해서는 안 됩니다:

agent:
  env:
    ANTHROPIC_API_KEY: "env:ANTHROPIC_API_KEY"
...

env: 접두사는 aienv에게 런타임(runtime) 시 호스트 환경으로부터 해당 값을 통과(passthrough)시키도록 지시합니다. 이를 통해 이미지는 이식성(portable)을 유지하고 해시 캐시(hash-cached)될 수 있습니다.

의존성 (Dependencies)

시스템 패키지나 커스텀 설치가 필요하신가요? 다음과 같이 선언하세요:

deps:
  packages: [nodejs, git, curl, golang-go, ripgrep]
  custom:
...

aienv는 빌드 타임(build time)에 이를 설치합니다. 이미지는 전체 YAML의 SHA-256 해시 값에 의해 캐싱됩니다. 무엇이든 변경하면 다음 활성화 시 이미지가 자동으로 재빌드됩니다.

원샷 모드 (One-Shot Mode) — 에이전트에게 할 일을 알려주고 떠나세요

이 기능이 바로 aienv가 빛을 발하는 지점입니다.

대화형 세션(interactive session)에 진입하는 대신, 프롬프트(prompt)를 직접 전송하여 에이전트가 독립적으로 작업하게 할 수 있습니다. 에이전트는 자신의 작업을 수행하고, 변경 사항을 커밋(commit)하며, PR(Pull Request)을 생성한 뒤 종료합니다. 컨테이너는 스스로 파괴(self-destructs)되며, 사용자는 깨끗한 감사 로그(audit log)를 얻게 됩니다.

aienv up claude-dev -p "Refactor the auth module to use JWT and create the PR using gh cli" -x

-p 플래그는 프롬프트를 전송합니다. -x 플래그는 **원샷 모드 (one-shot mode)**를 의미하며, TUI(Text User Interface)도 없고 기다릴 필요도 없습니다. 에이전트가 시작되어 실행한 후 바로 종료됩니다.

이는 CI/CD, 예약된 작업(scheduled tasks), 또는 직접 감독하고 싶지 않은 작업을 위임할 때 완벽합니다. 완전한 격리를 위해 아래에 설명된 git worktree와 결합하면, 에이전트가 호스트의 작업 트리(working tree)에 어떠한 부작용(side effects)도 미치지 않게 할 수 있습니다.

네트워크 권한 (Network Permissions)

기본적으로 에이전트는 필터링되지 않은 네트워크 액세스 권한을 가집니다. 허용 목록(allowlist)을 정의하면 그 외의 모든 것은 차단됩니다:

permissions:
  network:
    allow:
...

프록시(Proxy)는 호스트에서 Go HTTP/HTTPS 프록시로 실행됩니다. 컨테이너는 HTTP_PROXY/HTTPS_PROXY를 통해 해당 프록시를 가리키게 됩니다. 모든 요청은 허용 목록(allowlist)을 기준으로 검사됩니다.

학습 모드 (Learn Mode)

설정된 네트워크 규칙이 없나요? 프록시는 **학습 모드 (learn mode)**로 동작합니다. 에이전트가 접속하는 모든 호스트 이름을 기록하고, 세션이 종료될 때 권장 허용 목록을 출력합니다:

"claude-dev"에 대한 권장 permissions.network.allow:
  - api.anthropic.com
  - raw.githubusercontent.com
...

이 항목들을 YAML에 추가하면 보안 설정이 완료됩니다.

Git 워크트리 격리 (Git Worktree Isolation)

강력한 격리가 필요하다면 --worktree / -w를 사용하세요:

aienv up my-env -w feature/jwt-auth

이 명령은 **git 워크트리 (git worktree)**를 생성합니다. 이는 저장소의 .git 디렉토리를 공유하는 연결된 체크아웃(linked checkout)입니다. 생성된 워크트리를 에이전트의 작업 공간(workspace)으로 샌드박스 내에 마운트하며, 세션이 종료되면 정리합니다. 사용자의 메인 워킹 트리(working tree)는 깨끗하게 유지되며, 여러 에이전트가 서로 간섭 없이 동시에 서로 다른 브랜치에서 작업할 수 있습니다.

감사 추적 (Audit Trails)

모든 세션은 ~/.local/share/aienv/<name>/audit/<session-id>/ 경로에 JSONL 형식의 감사 로그(audit log)를 생성합니다:

session.meta.json    — 환경 이름, 에이전트 명령, 시작 시간
network.jsonl        — 모든 HTTP 요청 및 HTTPS CONNECT

각 활성화(activation)는 고유한 세션 ID를 부여받습니다. 동시에 실행되는 활성화들은 완전히 독립적입니다. 감사 디렉토리는 컨테이너 내부로 마운트되므로, 에이전트 내부의 스크립트가 비용 추출(cost-extraction) 데이터를 작성할 수 있습니다.

전체 예시: 권한, 워크트리 및 원샷(One-Shot)을 적용한 Claude Code

다음은 Claude Code를 사용한 자동 리팩터링을 위한 완전한 환경 설정 예시입니다:

env:
  name: claude-dev
  description: 내 프로젝트를 위한 샌드박스형 Claude Code
...

실행 방법:

# 대화형 세션
aienv up claude-dev

...

에이전트:

1. feature/jwt-auth 브랜치의 전용 git worktree에서 시작합니다.
2. Anthropic 및 GitHub API에만 접근할 수 있습니다.
3. 런타임(runtime) 시 GITHUB_TOKEN 및 ANTHROPIC_API_KEY가 주입됩니다.
4. 인증(auth) 모듈을 리팩터링(refactor)하고, 커밋(commit) 및 푸시(push)한 뒤 PR(Pull Request)을 생성합니다.
5. 종료됩니다. 컨테이너가 제거됩니다. 감사(audit) 로그가 기록됩니다. worktree가 정리됩니다.

호스트 오염 없음. 수동 정리 필요 없음. 완전한 추적 가능성.

기본 기능 그 이상

• 신뢰 프롬프트 (Trust prompts) — 첫 활성화 시 마운트(mount) 및 네트워크 규칙을 보여주고 확인을 요청합니다. YAML 해시(hash)로 캐싱되며, 설정이 변경되면 다시 프롬프트가 나타납니다.
• 디버그 셸 (Debug shell) — aienv shell <name>을 실행하면 에이전트 없이 샌드박스(sandbox) 내부의 /bin/bash로 바로 진입합니다.
• 정리 (Cleanup) — aienv clean은 고립된(orphaned) Docker 이미지, 감사(audit) 디렉토리 및 신뢰 캐시(trust cache) 항목을 제거합니다.
• 블랙박스 설계 (Black-box design) — 어떤 CLI 에이전트든 작동합니다. YAML에서 agent.install과 agent.command만 변경하면 됩니다. 코드 변경은 전혀 필요 없습니다.
• XDG 준수 (XDG-compliant) — 설정은 ~/.local/share/aienv/에, 신뢰 캐시는 ~/.config/aienv/trust/에 저장됩니다.

사용해 보기

go install github.com/kapilratnani/aienv@latest
aienv create my-env
aienv up my-env

이 프로젝트는 MIT 라이선스를 따르며, 기여를 환영합니다. 아키텍처 결정 기록(architecture decision records)은 공개되어 논의가 가능합니다.

github.com/kapilratnani/aienv에서 리포지토리(repo)에 스타(Star)를 눌러주시고, 문제가 발생하면 이슈(issue)를 생성해 주세요. 또한 샌드박스에서 어떤 에이전트를 실행하고 계신지 저희에게 알려주세요.

AI 코딩의 미래는 격리되어 있고, 감사 가능하며, 재현 가능합니다. aienv는 그 방향을 향한 한 걸음입니다.

이 기사는 aienv 샌드박스 내부에서 실행되는 AI 에이전트와 함께 작성되었습니다. 물론입니다.