AI 코딩 에이전트에게 저장소를 맡기려고 권한 구조를 네 구역으로 나눠 짜 봤습니다. 사람이 작업 문서를 주면, 자격증명이 없는 샌드박스에서 에이전트가 구현과 테스트를 합니다. 밖으로 나가는 것은 진짜 GitHub 토큰을 가진 유일한 곳인 git 게이트웨이를 거쳐 작업 브랜치와 초안 PR 로만 나가고, 마지막 방어선은 GitHub 의 서버 쪽 규칙과 CI 입니다. 리뷰와 병합은 사람이 합니다. 조사 시점은 2026년 11월 초입니다.

이 구조를 셀프호스팅 PaaS 에 올린다면 어떻게 될지 Coolify 기준으로 설계해 봤습니다. 아직 구축하지 않았고, 아래는 문서를 읽고 세운 계획입니다.

문서에서 확인한 것

서버 문서에 따르면 Coolify 는 연결한 서버를 SSH 로 관리합니다. 검증 과정에서 Docker 를 설치하고 서비스를 재시작할 수 있어서, 문서는 되도록 새 서버를 쓰라고 권합니다.

운영 작업에는 앱 활동이 Coolify 자체에 영향을 주지 않도록 원격 서버를 두라는 권장도 있습니다.

Destination 은 서버 위의 Docker 네트워크이고, 다른 네트워크의 리소스는 공유 네트워크에 연결하지 않으면 격리됩니다. Compose 앱을 다른 리소스와 통신시키는 "Connect To Predefined Network" 는 켜지 않습니다.

Custom Docker Options 는 --cap-add, --cap-drop, --security-opt, --sysctl, --device, --ulimit, --init, --privileged, --hostname, --entrypoint, --add-host, --pids-limit, --read-only, --runtime, --tmpfs 등을 허용합니다. --network, --name, -v, -p, -e 는 적용되지 않고 배포 로그에 경고가 남습니다. 문서는 --privileged, --device, 추가 권한이 컨테이너 격리 경계를 약하게 한다고 경고합니다.

gVisor, Sysbox, Kata 를 Coolify 와 함께 쓴다는 공식 근거는 찾지 못했습니다. --runtime 이 허용 목록에 있으니 서버의 Docker 데몬에 런타임을 등록하면 지정할 수는 있을 것으로 추론할 뿐이고, 돌려 보지 않았습니다.

Docker 문서에 따르면 데몬에 명령할 수 있으면 그 머신의 root 를 가진 것과 같습니다.

격리 기술은 각자 막는 것이 다릅니다. gVisor 문서는 샌드박스가 안전한 구조를 대신하지 못한다고 적습니다. Firecracker 문서는 네트워크 필터링을 하지 않는다고 밝힙니다. 어떤 격리든 에이전트에게 준 자격증명으로 하는 합법적 동작은 막지 못합니다. 그래서 격리 기술을 고르기 전에 자격증명을 어디에 둘지부터 정해야 한다는 생각이 들었습니다.

설계 결정

서버를 나눕니다. 샌드박스 서버는 운영 서버와 분리한 별도 VM 입니다. 같은 Docker 데몬과 커널을 나눠 쓰지 않습니다. 제어판에는 원격 서버로 등록합니다. 방화벽은 들어오는 SSH 를 제어판에서만 받고, 프록시가 허용한 곳 밖으로 나가는 통신을 막습니다.

게이트웨이와 샌드박스는 다른 리소스로 둡니다. Coolify 는 compose 리소스의 환경변수를 그 안 모든 서비스 컨테이너에 주입하고, compose 의 environment: 로는 좁힐 수 없습니다. compose 리소스의 env 경계를 다룬 앞선 글에서 직접 재 본 내용입니다. Coolify 문서에서 확인한 것이 아니라 제 실측입니다. 토큰을 든 게이트웨이를 같은 리소스에 넣으면 샌드박스에도 토큰이 들어갑니다.

시크릿이 없는 것끼리는 같은 리소스에 둬도 됩니다. 샌드박스, 테스트용 DB 사이드카, 외부 통신 프록시를 내부 전용 네트워크(internal: true)로 묶습니다.

외부 통신은 프록시로만 나갑니다. 허용 대상은 패키지 레지스트리와 게이트웨이뿐입니다. github.com 도 직접 열지 않습니다. Agentic Workflows 도 Squid 프록시와 도메인 허용 목록을 씁니다.

컨테이너 권한을 덜어 냅니다. 샌드박스 컨테이너에는 아래 옵션을 줍니다. 런타임을 등록했다면 --runtime=runsc 를 더하는 것까지가 계획이고, 앞서 적은 대로 이 조합은 돌려 보지 않았습니다. 비루트 사용자로 실행하고, --privileged, --device, --cap-add 는 쓰지 않습니다. 작업 폴더만 쓰기 가능한 볼륨으로 둡니다.

plaintext
--cap-drop=ALL --security-opt=no-new-privileges --pids-limit=512 --read-only --tmpfs /tmp

Docker 소켓은 샌드박스에도 게이트웨이에도 주지 않습니다. 작업마다 컨테이너를 만들게 하려면 게이트웨이에 소켓을 줘야 하는데, 그러면 토큰을 든 서비스가 호스트 root 까지 갖습니다. 앞에서 옮긴 Docker 문서의 문장이 그 뜻입니다. 개인 규모에서는 컨테이너 하나, 동시 작업 1개, 작업 전후 폴더 초기화가 단순합니다. 동시 실행이 필요해지면 그때 전용 런타임을 고르려고 합니다.

통합 테스트는 더미로 돌립니다. 에이전트가 Docker 를 쓸 수 없으므로 테스트 DB 는 미리 띄운 사이드카나 인메모리로 줍니다. 값은 더미입니다.

배포 뒤에는 키 이름을 셉니다. 샌드박스 컨테이너의 환경변수를 키 이름만 뽑아 시크릿 계열이 0개인지 봅니다.

bash
docker inspect <컨테이너> --format '{{range .Config.Env}}{{println .}}{{end}}' | cut -d= -f1 | sort

게이트웨이는 공용 인터넷에 열지 않습니다. 사설망이나 내부망으로 둡니다. 원격 에이전트 서비스에 MCP 로 열어야 한다면 OAuth 2.1 로 인증하고, token passthrough 를 하지 않습니다. MCP 스펙은 token passthrough 를 명시적으로 금지하고, MCP 서버 자신을 위해 발급되지 않은 토큰은 받지 말라고 못 박습니다.

정리하면, Coolify 에 에이전트 샌드박스를 올린다면 서버를 나누고, 토큰을 든 게이트웨이와 샌드박스를 다른 리소스로 두고, 외부 통신은 프록시로만 내보내고, Docker 소켓은 어디에도 주지 않으려고 합니다. 격리 기술을 고르기 전에 자격증명을 어디에 둘지부터 정해야 한다는 것이 이 설계의 출발점입니다. 네 구역의 설계와 git 게이트웨이 시험 19건, GitHub 룰셋 구성은 «AI 에이전트 권한 분리 설계»에 적었습니다.