OneCLI 직접 호스팅 및 Docker Compose 설치 가이드
OneCLI를 직접 호스팅하여 사용자별 샌드박스 에이전트를 구축하는 방법을 설명합니다. PostgreSQL 기반의 Docker Compose 구성과 에이전트당 2 GiB 메모리가 필요한 서버 사양 등 실제 운영에 필요한 기술적 세부 사항을 모두 정리했습니다.
OneCLI를 직접 호스팅할 때 얻는 이점
OneCLI를 직접 호스팅하면 팀원 각자가 자신만의 에이전트를 갖게 됩니다. 각 에이전트는 독립된 샌드박스에서 실행되며, API 키는 에이전트가 직접 읽을 수 없는 게이트웨이에 보관됩니다. 설치는 http://localhost:10254에서 접근 가능한 PostgreSQL 기반의 Docker Compose 스택으로 구성됩니다. 실제 서버 환경을 고려하십시오. 문서화된 기본값은 에이전트 샌드박스당 2 GiB 메모리 제한이므로, 기본 스택과 에이전트의 실제 작업 메모리를 별도로 예산에 반영해야 합니다.
해당 스택은 8개의 구성 요소로 이루어져 있으며, 각 역할을 이해하면 이후 가이드를 읽기가 더 수월합니다.
- 웹 대시보드 (Next.js), 포트
10254. 에이전트 생성, 채팅, 메모리 및 기술 편집, 연결 및 보안 설정. - API 서버, 포트
10256. 제어 평면: 데이터베이스, 대화 처리, 작업 큐. - Rust 게이트웨이, 포트
10255. 에이전트에서 나가는 요청을 가로채어 자격 증명을 주입. - 러너(Runner). README에 따르면 "에이전트 샌드박스를 시작, 정지, 회수하는 구성 요소입니다. 아웃바운드 전용이며 데이터베이스에는 접근하지 않습니다."
- 샌드박스 슈퍼바이저(Sandbox Supervisor). README에 따르면 "각 샌드박스 내부에서 실행되며, 에이전트 런타임을 교체할 수 있도록 벤더 중립적인 하니스 인터페이스를 사용합니다."
- SSH 터미네이터, 포트
10257. README에서는 이를 "SSH 정문"이라고 부릅니다. API가 발급한 단기 인증서로 SSH 연결을 종료하고 각 세션을 에이전트의 샌드박스로 연결합니다. 러너와 동일한runner프로필 하에서 실행됩니다. - 채널 어댑터. Slack 앱을 연결하는 데몬으로, 에이전트가 자신의 이름으로 채널 및 DM에서 응답할 수 있게 합니다.
- PostgreSQL. 제공된 compose 파일은
pgdata볼륨을 사용하는postgres:18-alpine를 실행합니다.
이름은 CLI지만, 제품은 서버입니다
OneCLI는 서버 플랫폼입니다. 이름 때문에 노트북에 설치하는 명령줄 도구로 오해하기 쉽지만, 이 가이드에서 다루는 대상은 그런 도구가 아닙니다. 별도의 명령줄 클라이언트는 onecli/onecli-cli 저장소에 존재하며, 이는 로컬 코딩 에이전트의 트래픽을 게이트웨이로 라우팅하는 역할을 합니다. 여기서 배포하는 것은 다중 사용자 웹 애플리케이션입니다. 여기에는 조직과 초대를 관리하는 계정 시스템, 대화와 비밀 정보를 담은 데이터베이스, 그리고 컨테이너를 실행하는 러너가 포함됩니다.
이 플랫폼은 1인 1에이전트 모델을 기반으로 설계되었습니다. README에 따르면 "사용자별로 에이전트를 생성하고, 필요한 접근 권한을 부여하면, 에이전트는 샌드박스 안에서 동작하며 게이트웨이를 통해 자격 증명을 주입받고 정책을 강제합니다." 각 에이전트는 고유한 파일 시스템과 셸, 대화 페이지, 플랫폼이 유지하는 메모리, 그리고 한 번 작성하면 재사용 가능한 기술(skills)을 가집니다. 자격 증명은 일반적인 설정 방식과 반대로 작동합니다. 각 사용자의 환경에 API 키를 복사해 넣는 대신, 키를 한 번 저장한 뒤 이를 사용할 권한이 있는 에이전트에게 부여하는 방식입니다.
시작하기 전에 필요한 환경
- Docker 및 2.24.0 버전 이상의 Compose 플러그인. 제공된 compose 파일은 Docker 2.24.0부터 지원하는 선택적
env_file매핑과required: false을 사용합니다. 마이그레이션 주석에는up --wait하위의 일회성 의존성을 지원하기 위해 2.19 버전이 최소 사양이라고 명시되어 있으나, 이는 해당 파일의 선택적 환경 파일까지는 지원하지 않습니다. - 메모리 용량은 실제 제약 사항입니다. 요금제를 선택하기 전에 아래의 사이징 섹션을 읽어 보십시오.
- 사용 가능한 루프백 포트
10254,10255,10256,10257및5432. 포트10257는 이 가이드에서 활성화하는runner프로필로 시작되는 SSH 관문입니다.
PostgreSQL을 직접 설치할 필요는 없습니다. compose 파일이 이를 서비스로 실행합니다. 아래의 설정 마법사는 호스트에 Node.js와 pnpm이 필요합니다. 코드 작업을 수행할 때도 mise을 사용하여 게이트웨이용 Rust를 포함한 툴체인을 고정합니다.
VPS 한 대에 에이전트 샌드박스를 몇 개나 올릴 수 있습니까?
러너 자체 문서에서는 막연한 추측이 아닌 실제 수치를 제공합니다. 각 샌드박스는 메모리 2048 MB(RUNNER_SANDBOX_MEMORY_MB), CPU 1개(RUNNER_SANDBOX_CPUS), 프로세스 512개(RUNNER_SANDBOX_PIDS)로 제한됩니다. 동시 실행 제한은 4개(RUNNER_MAX_SANDBOXES)이며, 문서에서는 이 제한을 충족하기 위해 기본 스택 외에 약 10 GiB의 여유 메모리를 확보할 것을 권장합니다.
이 차트의 데이터
[
{
"plan": "2 GB box",
"ram_gb": 2,
"sandbox_slots": 0
},
{
"plan": "4 GB box",
"ram_gb": 4,
"sandbox_slots": 1
},
{
"plan": "8 GB box",
"ram_gb": 8,
"sandbox_slots": 3
},
{
"plan": "16 GB box",
"ram_gb": 16,
"sandbox_slots": 7
},
{
"plan": "32 GB box",
"ram_gb": 32,
"sandbox_slots": 15
}
]이 슬롯 개수는 벤치마크가 아닌 산술적인 계산 결과입니다. 전체 메모리에서 PostgreSQL 및 기타 상주 서비스가 사용하는 약 2 GB를 제외한 뒤, 샌드박스 제한인 2 GiB로 나눈 값입니다. 이를 기준으로 2 GB box은 0개의 샌드박스가 최대 메모리 제한까지 사용할 수 있도록 예산을 책정합니다. 값이 0이라는 것은 이러한 가정하에 최대 용량으로 할당할 예산이 없다는 뜻이지, Docker가 에이전트 실행을 거부한다는 의미는 아닙니다. 16 GB box은 7개의 공간을 확보하며, 이는 기본 제한인 4개와 러너 문서에서 요구하는 약 10 GiB의 여유 메모리보다 넉넉한 수준입니다. 32 GB box을 선택하면 15개가 됩니다. 동시에 4개 이상을 실행하려면 RUNNER_MAX_SANDBOXES도 함께 높여야 합니다.
이 산술 계산을 변하게 하는 두 가지 요소가 있습니다. 백그라운드 프로세스가 실행 중인 샌드박스는 절대 대기 상태(park)로 전환되지 않으므로 슬롯을 영구적으로 점유합니다. 따라서 RUNNER_MAX_SANDBOXES는 가장 바쁜 순간이 아닌 지속적인 부하를 기준으로 산정해야 합니다. 플랫폼은 이에 대한 상한선을 둡니다. 기본적으로 각 러너는 최대 RUNNER_MAX_SANDBOXES에서 1을 뺀 개수만큼의 샌드박스를 대기 상태로 유지하며(최소 1개 이상, API의 MAX_HELD_AWAKE_SANDBOXES로 재정의 가능), 이를 초과하면 가장 오랫동안 유휴 상태였던 샌드박스를 제거하고 해당 프로세스가 손실된 것으로 보고합니다. 메모리와 CPU 사용량은 작업 내용에 따라 달라집니다. 각 샌드박스는 CPU 1개로 제한되므로 바쁜 에이전트 4개는 코어 4개를 사용할 수 있지만, 2 GiB 메모리 설정은 예약값이 아닌 상한선입니다. 즉, 유휴 상태인 에이전트 4개가 자동으로 8 GiB를 소비하지는 않습니다.
변경을 고려할 만한 러너 설정
RUNNER_MAX_SANDBOXES(기본값4): 동시에 실행할 샌드박스 개수.RUNNER_SANDBOX_MEMORY_MB(기본값2048): 샌드박스당 메모리 제한.RUNNER_SANDBOX_CPUS(기본값1): 샌드박스당 CPU 제한.RUNNER_SANDBOX_PIDS(기본값512): 샌드박스당 프로세스 제한.RUNNER_NETWORK_INTERNAL(기본값true): 샌드박스 네트워크의 외부 경로를 차단합니다. 켜두는 것을 권장합니다.RUNNER_SANDBOX_NETWORK(기본값onecli-sandboxes): 샌드박스가 참여할 네트워크.RUNNER_RECONCILE_SECONDS(기본값60): 러너가 상태를 조정하는 주기.RUNNER_ORPHAN_GRACE_SECONDS(기본값3600): 고아 컨테이너 및 볼륨을 삭제할 기준 시간.RUNNER_AGENT_IMAGE: 샌드박스 이미지를 재정의합니다. 설정하지 않으면ONECLI_VERSION를 따릅니다.
Docker Compose로 OneCLI 설치하기
업스트림의 셀프 호스팅 문서가 제공하는 원본 시퀀스는 docker/.env 파일 옆에 3개의 비밀 값을 기록합니다. 해당 시퀀스에는 서비스 활성화에 필요한 러너 토큰, Docker 소켓 그룹, SSH 자격 증명이 누락되어 있으므로 스택을 시작하기 전에 설정 마법사를 먼저 실행해야 합니다.
git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait실행하기 전에 해당 블록을 읽어 보십시오. heredoc 마커에 따옴표가 없으므로 셸이 각 head -c 32 /dev/urandom | base64를 실행하고 그 결과를 기록합니다. 리터럴 텍스트가 기록되는 것이 아닙니다. SECRET_ENCRYPTION_KEY는 데이터베이스 내 모든 비밀 값을 위한 AES-256-GCM 키입니다. GATEWAY_INTERNAL_SECRET은 게이트웨이가 API를 인증하는 데 사용됩니다. BETTER_AUTH_SECRET은 세션 쿠키에 서명합니다. COMPOSE_PROFILES=runner은 가장 중요한 행입니다. 러너 서비스가 Compose 프로필 뒤에 위치하기 때문입니다. 이 행을 생략하면 스택은 정상적으로 올라오지만 에이전트 샌드박스는 전혀 시작되지 않습니다.
--wait는 서비스가 실행 중이거나 정상 상태가 되고 마이그레이션 의존성이 성공적으로 완료될 때까지 대기합니다. 따라서 0이 아닌 종료 코드가 반환된다면 무언가 잘못되었다는 첫 번째 신호입니다. 그 후 실제로 어떤 서비스가 올라왔는지 확인하십시오.
docker compose ps
docker compose logs migrations버전을 고정하십시오. ONECLI_VERSION은 모든 서비스의 태그를 한 번에 설정하며, RUNNER_AGENT_IMAGE이 다른 곳을 가리키지 않는 한 에이전트 샌드박스 이미지도 이를 따릅니다. 버전 번호만 입력하십시오. 게시된 이미지 태그에는 v 접두사가 붙지 않습니다. 2026년 11월 1일 기준 최신 릴리스는 2026년 10월 31일에 게시된 v2.17.0입니다. 이 버전을 동일한 파일에 추가한 뒤, 문서화된 업그레이드 경로를 사용하여 실행 중인 샌드박스도 해당 이미지로 이동하도록 하십시오.
echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd dockercurl -fsSL https://onecli.sh/install | sh라는 설치 프로그램도 존재합니다. 이 프로그램은 설정을 ~/.onecli/.env에 기록하며 동일한 작업을 수행합니다. 이 프로그램은 실행 시 ONECLI_VERSION=latest을 설정하는데, 이는 .env 파일에만 보관된 고정 버전을 덮어씁니다. Compose 경로는 실행 전에 모든 파일을 읽을 수 있는 곳이며, 이미 다른 Compose 스택이 운영 중인 서버에서 사용하기 적합합니다. 위에서 설명한 체크아웃 설정은 pnpm run setup --upgrade을 통해 업그레이드합니다. 해당 경로는 호스트에 Node.js와 pnpm이 필요하며, 코드 자체를 수정하려면 게이트웨이를 위해 mise와 Rust가 추가로 필요하므로 OneCLI를 직접 수정하려는 사용자에게 적합합니다. Kubernetes의 경우 릴리스 v2.11.0(2026년 10월 8일)에서 Helm 차트가 추가되었습니다. 현재 차트는 에이전트 샌드박스를 영구 볼륨을 사용하는 Job으로 실행하며 Docker 데몬을 사용하지 않습니다. 또한 필요한 비밀 값, 데이터베이스 및 라우팅 설정을 문서화하고 있습니다.
노트북에서 대시보드 접속하기
제공된 compose 파일에 정의된 모든 포트는 ${ONECLI_BIND_HOST:-127.0.0.1}에 바인딩됩니다. VPS 환경에서 이는 대시보드가 실행 중이지만 외부에서는 접근할 수 없음을 의미합니다. 이 기본 설정은 올바른 상태입니다. 이 설정을 유지하고 SSH 터널을 사용하십시오.
ssh -N -L 10254:127.0.0.1:10254 you@your-server이제 노트북에서 http://localhost:10254을 엽니다. 트래픽이 SSH 연결을 통해 전달되므로 암호화되지 않은 대시보드가 공용 인터넷에 노출되지 않으며, 방화벽에 별도의 포트를 추가할 필요도 없습니다.
ONECLI_BIND_HOST=0.0.0.0 설정을 활성화하면 대시보드가 일반 HTTP로 공개되며, POSTGRES_PASSWORD를 설정하지 않을 경우 compose 파일의 기본 비밀번호인 onecli을 사용하는 PostgreSQL도 함께 노출됩니다. 또한 Docker 소켓을 마운트하는 서비스인 SSH front door가 10257 포트로 공개됩니다. 여러 사용자가 대시보드에 접근해야 한다면, TLS(transport layer security)가 적용된 리버스 프록시를 앞단에 배치하고 바인딩 호스트 설정은 그대로 두십시오. ONECLI_EXTERNAL_URL를 해당 HTTPS URL로 설정하고, 대시보드, API, 게이트웨이 경로를 각 서비스로 라우팅하는 upstream의 리버스 프록시 설정을 사용하십시오. 프록시만으로는 외부인의 접근을 완전히 차단할 수 없습니다. 셀프 호스팅 문서에 따르면 등록 기능은 설계상 항상 열려 있으며 이를 끄는 스위치는 없습니다. 대시보드에 접속하는 누구나 계정을 생성하여 자신만의 조직을 만들 수 있으며, 사용자의 조직에 가입할 때만 초대가 필요합니다. 따라서 대시보드를 네트워크 경계 내부로 유지하는 것이 권장됩니다. 만약 해당 프록시가 이미 다른 셀프 호스팅 앱의 앞단에 있다면, 셀프 호스팅 SSO(Single Sign-On) 계층을 통해 인증을 전달하여 팀이 이미 사용 중인 로그인 시스템 뒤에 대시보드를 배치하십시오. 이렇게 하면 한 곳에서 사용자를 삭제하는 것만으로도 이 접근 경로를 함께 차단할 수 있습니다.
첫 번째 계정을 생성하고 모델 키 권한 부여하기
대시보드를 열고 즉시 계정을 생성하십시오. 새로운 계정마다 고유한 조직이 생성되며, 팀원은 초대를 통해 귀하의 조직에 합류할 수 있습니다. 등록 기능은 이후에도 계속 열려 있으므로, 대시보드는 반드시 터널이나 인증된 프록시 뒤에 두어야 합니다. 로그인 기능이 도입되기 이전 버전에서 업그레이드하는 경우 즉시 등록하십시오. 셀프 호스팅 문서에 따르면 기존 데이터는 가장 먼저 등록한 계정으로 귀속되므로, 외부에서 접근 가능한 호스트라면 해당 계정이 귀하의 것이어야 합니다.
에이전트를 생성하기 전에 모델 키를 저장하십시오. 호스팅된 에이전트는 부여된 모델 키가 필요하며, 순서가 중요합니다. 대시보드에 키를 저장하고, 에이전트에 권한을 부여한 뒤에 대화를 시작하십시오. 권한 부여를 건너뛰면 샌드박스가 실행되지 않으며, 에이전트는 스레드 내에서 모델 키가 필요하다는 응답을 보냅니다.
권한은 필요한 만큼만 부여하십시오. 각 에이전트는 부여받은 권한만 사용할 수 있으며, 게이트웨이는 모든 요청마다 이를 강제합니다. 따라서 특정 저장소를 읽는 에이전트는 결제 서비스 제공업체의 키에 접근할 수 없습니다. 동일한 권한 목록을 통해 비용을 관리할 수 있습니다. 개인이 소유한 모든 모델을 호출할 수 있는 에이전트는 개인별 청구서로 이어지므로, 에이전트에게 권한을 부여하기 전에 에이전트의 모델 호출 비용 제한하기 문서를 읽어보는 것이 좋습니다.
게이트웨이가 에이전트로부터 키를 보호하는 방법
게이트웨이는 Rust로 작성된 HTTPS 프록시이며 10255 포트에서 대기합니다. 에이전트의 HTTP 클라이언트는 이 게이트웨이를 가리키며, 에이전트는 실제 자격 증명 대신 자리 표시자(placeholder) 자격 증명을 사용합니다. 게이트웨이는 아웃바운드 요청을 해당 에이전트의 권한과 대조하고, 실제 비밀 값을 복호화하여 요청에 삽입한 뒤 전달합니다. 비밀 값은 PostgreSQL에 AES-256-GCM(Advanced Encryption Standard, 256비트, Galois/Counter Mode)으로 암호화되어 저장되며, 요청 시점에만 복호화됩니다. 모든 호출은 에이전트의 식별 정보와 대상과 함께 기록되는데, 이는 키가 10명의 셸 프로필에 분산되어 있을 때는 얻을 수 없는 감사 추적(audit trail)입니다.
두 가지 메커니즘이 배포 방식을 결정합니다.
- HTTPS 가로채기는 중간자 공격(man-in-the-middle) 방식입니다. 게이트웨이는 로컬 인증 기관(CA)을 생성하고 에이전트가 이를 신뢰하게 함으로써, 에이전트의 TLS 연결을 종료한 뒤 업스트림 서비스로 향하는 새로운 연결을 엽니다. 이것이 바로 에이전트의 HTTP 클라이언트가 게이트웨이 인증 기관을 신뢰하지 않을 경우 인증 오류가 아닌 인증서 검증 오류가 발생하는 이유입니다.
- 에이전트는
Proxy-Authorization헤더를 통해 자신을 식별합니다. 에이전트와 게이트웨이가 내부 Docker 네트워크를 공유하는 단일 서버 환경에서는 해당 헤더가 사용자가 제어하지 않는 네트워크를 통과하지 않습니다. 서버 외부의 에이전트를 게이트웨이에 연결할 때는 VPN이나 TLS 전송 계층으로 연결을 보호해야 합니다. 해당 헤더는 베어러 토큰(bearer token)이기 때문입니다. 업스트림에서는 원시 CONNECT 프록시 포트에 대해 VPN 사용을 권장합니다.
정직한 거래: 게이트웨이는 설계상 에이전트가 보내는 모든 요청을 평문으로 읽습니다. 이는 시스템에서 가장 민감한 프로세스입니다. 따라서 해당 호스트를 그에 걸맞게 관리하고, 최소 권한 Linux 사용자를 통해 로그인 가능한 인원을 최소화하십시오.
러너에 인바운드 포트가 필요 없는 이유
러너는 아웃바운드 전용으로 동작합니다. 문서에 따르면 "러너는 외부에서 접근할 수 있는 포트를 열지 않으므로, 노트북, 홈랩, NAT 뒤에 있는 VPC 등 어떤 환경에서도 인그레스 설정, 터널링, TLS 종료 과정 없이 작동합니다." NAT는 네트워크 주소 변환(Network Address Translation)을 의미하며, 일반적인 가정용 공유기가 수행하는 기능입니다. 러너는 제어 평면(control plane)으로 먼저 연결을 시도하여 작업을 가져오므로, 포트 포워딩을 하거나 방화벽을 열 필요가 없습니다.
이러한 설계는 샌드박스 네트워크에서 효과를 발휘합니다. compose 파일은 internal: true로 표시된 두 번째 네트워크를 정의하는데, Docker에서 이는 외부 네트워크 연결이 차단됨을 의미합니다. 샌드박스는 이 네트워크에 참여합니다. 게이트웨이는 두 네트워크 모두에 연결된 듀얼 홈(dual-homed) 상태이므로, 외부로 나가는 유일한 경로가 됩니다. 러너 문서는 이 점을 명확히 설명합니다. "게이트웨이가 듀얼 홈으로 연결된 internal 네트워크는 게이트웨이 전용 이그레스를 단순한 권고 사항이 아닌 강력한 경계로 만듭니다." 에이전트는 외부 주소로 직접 연결을 시도하여 게이트웨이를 우회할 수 없으며, 어떤 요청을 허용할지는 여전히 게이트웨이의 정책에 따라 결정됩니다.
위 내용을 단순히 믿기보다 직접 자신의 장비에서 확인해 보십시오.
docker network ls
docker network inspect onecli-sandboxes | grep -i internal"Internal": true가 출력되어야 합니다. 만약 false으로 표시된다면 이그레스 제어 기능이 꺼진 상태이며, 게이트웨이는 다시 단순한 권고 사항으로 전락합니다. onecli-sandboxes는 기본값일 뿐이므로, docker network ls 명령이 출력하는 샌드박스 네트워크 이름을 사용하십시오.
OneCLI 샌드박스의 보안 수준은 어느 정도입니까?
이 섹션은 천천히 읽어 주십시오. 프로젝트 설명에서 "샌드박스(sandboxed)"라는 용어는 매우 비중 있게 다뤄지지만, 실제 메커니즘은 러너(runner) 문서와 백엔드 코드에 기술되어 있기 때문입니다.
README에 따르면 각 에이전트는 "파일 시스템과 셸을 갖춘 고유한 격리 샌드박스"를 할당받으며, "각 샌드박스 내부에서 실행되어 벤더 중립적인 하니스 인터페이스를 통해 에이전트 런타임을 교체 가능하게 만드는" 컴포넌트로 Sandbox Supervisor를 명시합니다. 하지만 이 문장들만으로는 격리가 어떤 방식으로 이루어지는지 알 수 없습니다. 러너 문서에는 기본 백엔드가 Docker(RUNNER_BACKEND=docker)라고 명시되어 있으며, 샌드박스는 메모리 제한, CPU 제한, 프로세스 제한이 적용되고 내부 네트워크에 연결된 Docker 컨테이너라고 설명합니다. 코드에는 다른 백엔드를 위한 연결 지점이 마련되어 있습니다. 현재 러너 코드는 Kubernetes 백엔드도 구현하고 있으며, Helm 차트는 이를 샌드박스 Job과 영구 볼륨(persistent volume)에 사용합니다. 이 가이드의 Compose 설치 환경에서 샌드박스는 Docker 컨테이너입니다.
러너 문서는 이제 Docker 경계를 다음과 같이 설명합니다. 에이전트는 node로 실행되며, no-new-privileges가 적용되고, 모든 Linux 기능(capabilities)이 제거되며, Docker의 기본 seccomp 프로필이 사용됩니다. 백엔드는 에이전트의 영구 홈 디렉터리만 샌드박스에 마운트합니다. 따라서 이를 좁은 의미로 해석해야 합니다. 제한 사항은 리소스 제한입니다. 내부 네트워크는 실질적인 외부 통신 제어 수단입니다. 에이전트와 호스트 사이의 격리는 이러한 컨테이너 제어 기능을 사용하며, 컨테이너는 호스트 커널을 공유합니다.
고려해야 할 두 번째 사실이 있습니다. 러너 서비스는 /var/run/docker.sock을 마운트하는데, 이는 샌드박스를 생성하는 방식이기 때문입니다. 루트 권한을 가진 Docker 데몬 소켓에 접근하는 것은 호스트의 루트 권한을 갖는 것과 동일합니다. 해당 API를 호출할 수 있는 사람은 누구나 호스트 파일 시스템을 마운트한 컨테이너를 시작할 수 있기 때문입니다. Docker 기반으로 제공되는 러너는 이 소켓을 사용합니다. 그 결과, 러너 프로세스는 게이트웨이만큼이나 민감한 보안 대상이 됩니다. SSH 터미네이터 역시 샌드박스 컨테이너 내부에서 exec 명령을 수행하기 위해 동일한 소켓을 마운트합니다. compose 파일의 주석에서도 이 마운트가 호스트의 루트 권한과 동등하다고 명시하고 있으므로, 특별한 이유가 없다면 포트 10257은 루프백(loopback)으로 유지하십시오.
공유 커널 경계는 보수적으로 다루어야 합니다. 실무적으로는 다음 세 가지 습관을 권장합니다.
- OneCLI는 다른 작업이 없는 전용 서버에서 실행하십시오. 관련 없는 프로덕션 서비스, 공유 데이터베이스, 다른 팀의 데이터를 함께 두지 마십시오.
- 샌드박스 내부에서 임의 코드 실행이 가능한 에이전트가 호스트까지 도달할 수 있다고 가정하십시오. 해당 상황이 발생하더라도 서버 외부의 백업을 통해 복구할 수 있도록 대비하십시오.
- 동료에게 에이전트가 완벽히 격리되어 있다고 말하기 전에
apps/runner/src을 읽거나 업스트림에 문의하십시오.
문서화된 경계가 어떤 의미인지, 그리고 업스트림에 어떤 질문을 던져야 할지 파악하려면 실제 에이전트 샌드박스 경계의 모습과 비교해 보십시오. 핵심은 문서화된 메커니즘이 귀하가 방어하고자 하는 위협을 충분히 차단하는지 확인하는 것입니다.
라이선스 분리와 빌드 전 확인이 필요한 이유
OneCLI의 핵심 코드는 Apache-2.0 라이선스를 따르며, 프로덕션 환경에서 직접 호스팅하는 것이 허용됩니다. ee/라는 이름의 디렉터리는 별도의 OneCLI Enterprise License를 따릅니다. 이 라이선스는 개발, 테스트, 평가 용도로는 무료이지만, 프로덕션 환경에서 사용하려면 구독이 필요합니다. 2026년 8월 18일에 릴리스된 v2.0.1 릴리스 노트에는 GitHub에서 감지 가능한 Apache-2.0 라이선스 파일을 복구했다는 내용이 포함되어 있어, 최근 저장소 페이지의 배지 정보가 변경되었습니다. 특정 날짜에 작성된 요약본을 보기보다는 실제로 배포하려는 태그를 직접 확인하십시오.
cd onecli && find . -type d -name ee -not -path '*/node_modules/*'해당 경로 아래에 있는 모든 항목은 상용 라이선스 대상입니다. 의존하려는 기능이 해당 경로에 포함되어 있다면, 프로세스를 구축하기 전에 비용을 먼저 산정하십시오.
업그레이드, 마이그레이션, 그리고 절대 잃어버려서는 안 될 파일 하나
업그레이드를 수행할 때는 서비스 이미지와 별도의 에이전트 이미지를 모두 새로 고친 다음, 실행 중인 샌드박스를 재시작해야 합니다. 모든 up에서는 API가 시작되기 전에 일회성 마이그레이션 서비스가 실행되며, 마이그레이션이 실패하면 스택은 절반만 마이그레이션된 스키마로 서비스를 제공하는 대신 시작 자체를 거부합니다. 이는 조용한 데이터 손상보다는 차라리 서비스 중단처럼 보이는 것이 문제 파악에 유리하기 때문에 의도된 동작이며, docker compose logs migrations에서 그 이유를 설명합니다.
한 가지 놓치기 쉬운 단계가 있습니다. 셀프 호스팅 문서에서는 단순히 docker compose pull && docker compose up -d만 사용하여 업그레이드하는 것을 경고하는데, 이는 에이전트 샌드박스 이미지가 Compose 서비스가 아니기 때문입니다. 해당 이미지는 러너의 RUNNER_AGENT_IMAGE 값으로 지정되어 있으므로 docker compose pull는 이를 인식하지 못하며, 호스팅된 에이전트는 경고 없이 이전 샌드박스 이미지에 머물 수 있습니다. 체크아웃을 업데이트하고 핀(pin)을 이동한 뒤, 문서화된 업그레이드 도구를 실행하여 샌드박스 이미지를 가져오고 실행 중인 샌드박스를 재시작하십시오.
cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations2.17.0을 이동하려는 릴리스 버전으로 교체하십시오. 샌드박스를 재시작하면 진행 중인 작업이 중단되지만, 각 에이전트의 영구 작업 공간(durable workspace)은 유지됩니다.
설치 스크립트를 사용하여 설치한 경우에는 수동으로 이미지를 가져오지 말고 스크립트를 다시 실행하십시오. 그래야 Compose 파일이 참조하는 이미지와 동기화된 상태를 유지할 수 있습니다. 특정 릴리스로 업그레이드하려면 먼저 ONECLI_VERSION를 내보내십시오. 스크립트는 자체 .env 파일에 보관된 핀 설정을 덮어쓰기 때문입니다.
데이터베이스, 구성 파일, 에이전트 작업 공간 볼륨을 백업하십시오. PostgreSQL에는 에이전트, 대화 내용, 메모리, 암호화된 비밀 정보가 저장됩니다. docker/.env 파일에는 SECRET_ENCRYPTION_KEY이 포함되어 있으며, 이 키가 없으면 데이터베이스의 나머지 부분을 복구하더라도 암호화된 비밀 정보를 읽을 수 없습니다. 각 에이전트의 /workspace은 별도의 영구 볼륨에 저장되므로 각각 별도의 백업이 필요합니다.
cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup이러한 복사본과 작업 공간 백업은 서버 외부의 안전한 곳에 보관하십시오. 이는 상태를 유지하는 모든 Compose 스택에 필요한 동일한 절차입니다. 따라서 이미 Docker Compose 스택 백업 및 업그레이드를 정기적으로 수행하고 있다면, 데이터베이스, 구성 파일, 작업 공간 볼륨을 백업 대상에 추가하여 관리하십시오.
작동하지 않을 때
- 스택이 정상 상태가 되지 않고
docker compose up -d --wait가 0이 아닌 종료 코드를 반환합니다. API가 해당 서비스를 의도적으로 대기하므로docker compose logs migrations을 먼저 읽어 보십시오. - 에이전트가 유휴 상태로 머물고 샌드박스가 나타나지 않습니다.
COMPOSE_PROFILES=runner이docker/.env에 포함되어 있는지,docker compose ps에 러너가 나열되어 있는지 확인하십시오. 그런 다음 에이전트에 부여된 모델 키가 있는지 확인하십시오. 모델 키 없이는 샌드박스가 실행되지 않습니다. - 슬롯이 부족합니다.
RUNNER_MAX_SANDBOXES는 기본값이 4이며, 백그라운드 프로세스가 실행 중인 샌드박스는 유지 제한(held-awake ceiling)에 의해 제거될 때까지 슬롯을 점유합니다.docker ps를 통해 실제로 활성화된 항목을 확인할 수 있습니다. - 스택이 시작되지 않고 Docker가 포트가 이미 사용 중이라고 보고합니다.
runner프로필이 켜져 있으면 SSH 관문은 다른 4개의 포트 외에도10257을 추가로 요구합니다. - 컨테이너가 사라지거나 호스트 성능이 급격히 저하됩니다.
dmesg -T | grep -i oom을 사용하여 메모리 부족 현상을 확인하십시오. 기본 메모리 제한에 따라 단일 샌드박스는 최대 2048 MB까지 사용할 수 있습니다. - 에이전트의 HTTPS 호출이 인증 오류가 아닌 인증서 검증 오류로 실패합니다. 이는 에이전트의 HTTP 클라이언트가 게이트웨이의 인증 기관(CA)을 신뢰하지 않기 때문입니다.
- 에이전트를 삭제한 후에도 이전 컨테이너나 볼륨이 남아 있습니다. 러너는 60초마다 조정 작업을 수행하며
RUNNER_ORPHAN_GRACE_SECONDS(기본값 3600)보다 오래된 고아 리소스를 삭제합니다. 따라서 누수라고 판단하기 전에 한 시간 정도 기다려 보십시오.
이 도구를 실행하는 것이 적절한 선택입니까?
적합성 테스트는 짧습니다. 여러 사람이 각자 에이전트를 필요로 하고 자격 증명을 한곳에서 관리해야 할 때 OneCLI가 유용합니다. 자격 증명을 순환시킬 저장소 하나, 감사 로그 하나, 그리고 특정인의 접근 권한을 취소했을 때 실제로 권한이 회수되는 대시보드 하나가 필요하기 때문입니다. 이는 실질적인 운영상의 문제이며, API 키를 6대의 노트북에 복사하는 것은 이에 대한 나쁜 해결책입니다.
한 사람이 사용하기에는 이 구성이 지나치게 복잡하며 얻는 이점도 없다. 단일 agent 하나를 제공하려면 PostgreSQL, control plane, gateway, runner를 각각 실행해야 한다. gateway가 해결하는 credential 문제도 key를 보유한 사람이 본인뿐이라면 거의 발생하지 않는다. 대신 더 작은 장비에서 단일 harness를 실행하면 된다. VPS에서 단일 agent harness 실행으로 메모리의 일부만 사용해 같은 작업을 수행할 수 있다. 아직 방향을 전혀 정하지 않았다면 self-hosted AI agent 비교에 있는 survey부터 확인하는 편이 비용이 적게 든다. 익숙하지 않은 부분이 agent 자체이지 agent가 실행되는 서버가 아니라면 먼저 agent의 실제 작동 방식을 배우는 단계별 경로를 따라가야 한다. tool call과 memory store가 실제로 무엇을 하는지 알아야 각 사람의 agent에 어떤 권한을 부여할지 결정할 수 있기 때문이다.
FAQ
OneCLI를 자체 호스팅하기 위한 최소 서버 사양은 무엇입니까?
Docker Compose 플러그인 2.24.0 버전 이상, 설치 마법사를 위한 Node.js와 pnpm, 그리고 충분한 메모리가 필요합니다. PostgreSQL은 compose 파일에 포함되어 있으므로 별도로 설치할 필요가 없습니다. 메모리 용량은 운영 계획에 따라 결정됩니다. 러너(runner)는 기본적으로 각 에이전트 샌드박스를 2048 MB로 제한하며, 기본값인 4개의 샌드박스를 수용하려면 기본 스택 외에 약 10 GiB의 여유 메모리가 필요합니다. 차트에서 가정한 2 GB의 기본 스택 예산을 기준으로, 4 GB 서버는 1개의 샌드박스를 최대치로 운영할 수 있고, 16 GB 서버는 기본 동시성 제한을 모두 수용할 수 있습니다. 이는 계획을 위한 수치이며, 측정된 최소 요구 사항이나 고정된 메모리 할당량은 아닙니다.
OneCLI는 PostgreSQL이 필요한가요, 아니면 SQLite를 사용할 수 있나요?
PostgreSQL이 필요합니다. DATABASE_URL은 PostgreSQL 연결 문자열로 문서화되어 있으며, 제공된 compose 파일은 pgdata 볼륨을 사용하는 postgres:18-alpine을 실행합니다. 또한 API가 시작되기 전에 별도의 마이그레이션 서비스가 스키마를 적용합니다. SQLite 옵션은 문서화되어 있지 않습니다. 외부 PostgreSQL 서버를 사용하는 경우, API와 마이그레이션 서비스 모두 해당 서버를 사용하도록 설정하십시오. 제공된 compose 파일은 이들의 연결 문자열을 번들로 포함된 PostgreSQL 서비스로 설정합니다.
OneCLI 에이전트 샌드박스는 실제 보안 경계인가요?
문서화된 Compose 메커니즘은 메모리, CPU, 프로세스 제한이 적용된 Docker 컨테이너이며, 외부 트래픽이 게이트웨이를 통과하도록 internal: true으로 표시된 네트워크에 연결됩니다. 송신 제어는 실제로 작동하며 docker network inspect를 통해 확인할 수 있습니다. 에이전트는 node로 실행되며, no-new-privileges이 적용되고 모든 Linux 기능(capabilities)이 제거된 상태에서 Docker의 기본 seccomp 프로필을 사용하지만 호스트 커널은 공유합니다. 러너와 SSH 터미네이터는 모두 /var/run/docker.sock을 마운트하는데, 이는 rootful Docker 데몬을 사용하는 호스트의 root 권한과 동일합니다. OneCLI는 전용 서버에서 실행하고, 백업은 해당 서버 외부에 보관하십시오.
OneCLI를 위해 인바운드 포트를 열어야 하나요?
아니요. 러너는 아웃바운드 전용이며 외부에서 접근 가능한 포트를 열지 않으므로, 터널 없이 NAT 뒤에서도 작동합니다. compose 파일은 대시보드, 게이트웨이, API, PostgreSQL을 기본적으로 127.0.0.1에 바인딩하며, runner 프로필 사용 시 SSH 접속 포트인 10257도 동일하게 바인딩합니다. SSH 터널을 통해 대시보드에 접근하거나, 여러 사용자가 필요한 경우 TLS가 적용된 업스트림 리버스 프록시 설정과 대시보드, API, 게이트웨이 경로를 사용하십시오. 단, 접근 가능한 모든 사용자에게 등록 기능이 열려 있다는 점을 유의해야 합니다. 10255 포트의 게이트웨이는 에이전트를 위한 것이며, 단일 서버 환경에서는 에이전트가 내부 Docker 네트워크를 통해 해당 포트에 접근합니다.
OneCLI를 회사 내부에서 무료로 사용할 수 있나요?
핵심 코드는 Apache-2.0 라이선스를 따르며, 상업용 라이선스 없이 자체 호스팅 환경에서 프로덕션 용도로 사용할 수 있습니다. ee/이라는 이름의 디렉터리는 OneCLI Enterprise License의 적용을 받습니다. 이 라이선스는 개발, 테스트, 평가 목적으로는 무료이지만 프로덕션 환경에서는 구독이 필요합니다. 라이선스 적용 범위는 릴리스마다 변경될 수 있습니다. 2026년 8월 18일 자 v2.0.1 릴리스 노트에는 GitHub에서 감지 가능한 Apache-2.0 라이선스 파일을 복구했다는 내용이 포함되어 있으므로, 특정 기능을 기반으로 워크플로를 구축하기 전에 배포하려는 태그의 LICENSE 및 ee/ 디렉터리를 확인하십시오.