AI 코딩 하네스와 중계 — 로컬 도구 루프 · 원격 추론 · 막혔을 때의 아키텍처
Grok Build · Cursor CLI는 어떻게 둘로 나뉘는가, 그리고 A가 모델 도메인에 못 갈 때 B를 어떻게 세우는가
맞습니다. Grok Build나 Cursor CLI 같은 AI 코딩 에이전트는 개념적으로 ① 내 컴퓨터를 제어하는 부분(하네스) 과 ② 모델 서버와 통신하는 부분(추론 API 호출) 으로 깔끔하게 나뉩니다. 파일을 읽고 셸을 돌리는 일은 전부 로컬에서 일어나고, "다음에 뭘 할지"를 정하는 추론만 원격 HTTPS로 나갑니다.
그래서 컴퓨터 A가 grok.com·claude.com·모델 API에 못 나가더라도,
추론 트래픽만 컴퓨터 B를 통해 내보내거나(S2), 아예 하네스째로 B에서 돌리면(S3)
코딩 에이전트를 쓸 수 있습니다. 이 문서는 그 개념과 방법론을 정리합니다.
1. 하네스란 무엇인가
1-1. 두 층 — 하네스(로컬) vs 모델 서버(원격)
하네스(harness)는 원래 "말에 씌우는 마구(馬具)"라는 뜻입니다. AI 에이전트에서는 모델 주변에 씌우는 발판을 가리킵니다 — 모델 가중치 자체가 아니라, 컨텍스트를 모으고 → 모델을 호출하고 → 응답을 파싱하고 → 도구 호출을 실행하는 루프가 하네스입니다. SpaceXAI가 오픈소스로 공개한 Grok Build의 설명도 이와 같습니다.
| 층 | 역할 | 실행 위치 | 전형적 프로토콜 |
|---|---|---|---|
| 하네스 (harness) |
컨텍스트 조립, 도구 디스패치, 권한·샌드박스, 세션 / TUI / ACP | 로컬 (또는 개발 머신) | 파일 · 셸 · 브라우저 · MCP · stdio |
| 모델 서버 (inference) |
토큰 생성 · 추론 · (일부) 서버측 도구 | 원격 API 또는 자체 호스트 | HTTPS(REST) · HTTP/2 · Connect-RPC / gRPC · SSE |
1-2. 로컬 도구 루프와 원격 추론
한 턴은 이렇게 흐릅니다. 사용자가 무언가를 시키면 하네스가 워크스페이스·히스토리·도구 스키마를 묶어
모델에 보내고, 모델은 텍스트 또는 tool_call JSON을 스트림으로 돌려줍니다.
하네스는 그 도구 호출을 로컬에서 실행하고, 결과를 다음 턴 메시지에 다시 실어 보냅니다.
충분해질 때까지 이 루프가 반복됩니다.
1-3. 무엇이 로컬에 남고 무엇이 원격으로 나가나
- 파일 변경 · git 작업 결과
- 셸 부작용(설치·빌드·프로세스)
- 세션 로그 (
~/.grok/, Cursor 로컬 상태) - 권한 승인 UI · 샌드박스 정책
- 프롬프트 · 선택된 코드 컨텍스트
- 도구 스키마 · 도구 결과 요약
- 스트리밍 응답(텍스트 / tool_call)
- 보존 여부는 제품·정책마다 다름 (제로 리텐션 옵션 등)
2. 정상 경로 (S1) — A가 직접 모델에 붙을 때
먼저 아무 제한이 없을 때의 흐름을 확정해 둡니다. 컴퓨터 A는 코드가 있는 개발 머신이고, 모델 도메인으로 직접 egress가 가능합니다. 이 8단계가 나중에 어디를 끊고 어디를 우회시킬지의 기준선이 됩니다.
3. 제한 상황 — A는 막히고 B는 열려 있다
이제 전제를 바꿉니다. A에는 코드가 있지만 모델·인증 도메인으로 나갈 수 없고, B는 나갈 수 있지만 A의 디스크를 보지 못합니다. 이 비대칭이 모든 설계의 출발점입니다.
3-1. A / B 능력 비교
| 주체 | 가능한 것 | 막힌 것 (가정) |
|---|---|---|
| A | 로컬 파일 · git · 셸 · IDE | grok.com / api.x.ai / claude.com / api.anthropic.com / *.cursor.sh 등 모델·인증 CDN 직접 접근 |
| B | 위 도메인 egress, 또는 이미 허용된 기업 프록시 · 배스천 | A의 디스크를 기본적으로는 못 봄 (별도 동기화·원격 FS 필요) |
3-2. 설계 질문은 하나가 아니다
4. 중계 패턴들
4-0. 다섯 패턴 한눈에
중계 방법은 크게 다섯 갈래입니다. 왼쪽이 A, 가운데가 B의 역할, 오른쪽이 모델입니다. ①②③은 하네스가 A에 남고, ④는 하네스가 B로 가고, ⑤는 자동화 자체를 포기합니다.
4-1. SSH · 터널 (SOCKS · 로컬 포워드 · 리버스)
| 기법 | 방향 · 의미 | 하네스 위치 |
|---|---|---|
ssh -D (동적 SOCKS) | A → B로 SSH, A의 앱이 SOCKS5로 B의 egress를 사용 | A |
ssh -L (로컬 포워드) | A의 로컬 포트 → B를 경유해 특정 호스트:443 | A |
ssh -R (리버스) | B(또는 외부)가 A 쪽 서비스에 닿게 함 — "A가 모델에 못 감"의 주역은 아님 | 상황 의존 |
| Jump / bastion | A → 배스천 → B(또는 인터넷) | A 또는 B |
- 장점 — 표준적이고, SSH 세션이 감사 가능하며, 앱이
HTTPS_PROXY/ALL_PROXY(SOCKS)만 따르면 됨 - 단점 — 지연·대역 손해. HTTP/2와 장시간 스트림이 SSH·프록시에서 끊기거나 버퍼링될 수 있음. SOCKS를 아예 지원하지 않는 클라이언트도 있음(Claude Code 공식 문서: SOCKS 미지원, HTTP(S) 프록시만)
- 보안 — SSH 키·에이전트 포워딩 남용 주의. 터널 끝(B)의 권한이 사실상 A의 인터넷 신분이 된다
4-2. HTTP(S) 프록시 · 기업 프록시 · PAC
표준 환경변수로 붙습니다.
HTTP_PROXY/HTTPS_PROXY/NO_PROXY- PAC(WPAD)는 브라우저·일부 OS 스택 전용에 가깝고, CLI는 PAC를 직접 읽지 않고 확정 URL을 환경변수로 받는 경우가 많습니다
| 제품 | 프록시 지원 (공개 문서 기준) | 비고 |
|---|---|---|
| Claude Code | HTTPS_PROXY 등 지원 · SOCKS 미지원 |
allowlist: api.anthropic.com, claude.ai, platform.claude.com, mcp-proxy.anthropic.com 등. 게이트웨이 사용 시 ANTHROPIC_BASE_URL |
| Cursor CLI / IDE | HTTP_PROXY / HTTPS_PROXY, NODE_USE_ENV_PROXY=1 · TLS 검사 시 NODE_EXTRA_CA_CERTS |
공식 allowlist: *.cursor.sh, *.cursor-cdn.com, *.cursorapi.com … 세분하면 api2.cursor.sh(일반 API), api5.cursor.sh(에이전트), api3 · repo42 등. HTTP/2 스트림이 깨지면 HTTP/1.1 모드(network.useHttp1ForAgent 등) |
| Grok Build | 커스텀 base_url / GROK_CLI_CHAT_PROXY_BASE_URL / [endpoints]로 자체 추론 프록시에 붙는 경로가 문서화됨 |
공개 API https://api.x.ai (관리 API https://management-api.x.ai), 로그인은 auth.x.ai / grok.com 세션. OS 프록시 준수 여부는 런타임·버전마다 다를 수 있어 환경에서 확인 필요 |
- 장점 — 기업 IT가 이미 허용한 egress 경로와 맞추기 쉽고, 로깅·DLP 연동이 자연스러움
- 단점 — SSL inspection + HTTP/2 양방향 스트림 충돌이 흔함. NTLM·Kerberos 인증은 로컬 헬퍼(cntlm 등)가 필요할 수 있음
- 보안 — 프록시 자격증명을 URL에 넣으면 셸 히스토리·프로세스 목록에 그대로 노출됨
4-3. API 게이트웨이 · 리버스 프록시
B(또는 기업 LLM Gateway)가 업스트림을 대신 호출하고, A는 게이트웨이 한 호스트만 봅니다. 아래 세 질문을 먼저 풀고, 그다음 그림·키·헤더 개념으로 이어갑니다.
api.x.ai 등) 그대로.리버스 프록시 · API 게이트웨이는 “목적지를 대신함” — 클라이언트가 아는 주소는 게이트웨이뿐.
업스트림 키는 벤더 본계정 API 키·토큰. 게이트웨이 전용 키와는 별개이며, 보통 B에만 둡니다.
포워드 프록시 vs 리버스 프록시
클라이언트 → (프록시) → 원래 도메인.
앱은 여전히 “어디에 갈지”를 알고, 프록시는 CONNECT·터널로 길만 열어 줍니다.
HTTPS_PROXY, ssh -D(SOCKS) 계열이 여기에 가깝습니다.
비유: 대리 운전으로 원래 가게에 간다. 간판은 그대로다.
클라이언트 → 게이트웨이만 → (뒤에서) 업스트림 API.
앱의 base_url / ANTHROPIC_BASE_URL / Grok 커스텀 엔드포인트가
B(또는 기업 LLM Gateway)를 가리킵니다.
비유: 프랜차이즈 창구 하나만 알고, 뒤는 본사·물류가 처리한다.
업스트림 키란?
업스트림 키는 Anthropic / xAI / Cursor 등 벤더 본계정에 발급된 API 키·세션 토큰입니다. 게이트웨이가 “뒤에서” 벤더 API를 호출할 때 쓰는 진짜 신분증이고, A가 들고 다니는 게이트웨이 전용 키(팀 내부 발급)와는 다릅니다.
- 왜 B에만 두나 — 유출: A 노트북·티켓·채팅에 벤더 키가 퍼지면 유출 면적이 커집니다. B(또는 시크릿 스토어)에만 두면 회수·교체가 쉽습니다.
- 왜 B에만 두나 — 감사: 누가 어떤 모델을 얼마나 썼는지 게이트웨이 로그 한곳에서 봅니다.
- 왜 B에만 두나 — 쿼터: 팀·프로젝트 단위 한도·모델 라우팅을 중앙에서 걸 수 있습니다.
- Claude Code —
ANTHROPIC_BASE_URL을 게이트웨이로, 클라이언트에는 게이트웨이 토큰 - Grok Build — 커스텀
base_url/GROK_CLI_CHAT_PROXY_BASE_URL/[endpoints] - 기업 LLM Gateway — 팀이 정한 단일 호스트. A 방화벽 allowlist가 그 한 곳으로 단순해짐
| 대상 | 일반적인 베이스 (공개 문서 기준) |
|---|---|
| xAI 추론 | https://api.x.ai (/v1/responses, /v1/chat/completions …) — Bearer XAI_API_KEY |
| Anthropic | https://api.anthropic.com — Claude Code는 ANTHROPIC_BASE_URL로 게이트웨이 치환 가능 |
| Cursor 에이전트 백엔드 | 공식 api2.cursor.sh, api5.cursor.sh(에이전트). CLI 예시 agent -e https://api2.cursor.sh. Connect-RPC / HTTP2 기반이며, 공개 "OpenAI 호환 채팅 API"가 아니라 Cursor 계정·프로토콜에 묶인 면이 큼 |
| Cursor Cloud Agents API | https://api.cursor.com (Basic/Bearer) — 클라우드 에이전트 오케스트레이션. 로컬 하네스 중계와는 별개 축 |
- 장점 — A의 방화벽 allowlist가 게이트웨이 하나로 단순해지고, 업스트림 키는 B에만 두며, 감사·쿼터·모델 라우팅이 중앙화됨
- 단점 — 게이트웨이가 스트리밍·도구 스키마·Cursor Connect 프로토콜을 정확히 중계해야 함. 단순
proxy_pass로는 부족한 경우가 있음 - 지연 — A↔B, B↔벤더로 한 홉이 늘어남
- 포워드와의 실무 차이 — 포워드는 “원래 도메인 egress만 열리면” 되고, 게이트웨이는 “프로토콜 호환 프록시 소프트웨어”가 추가로 필요함
grok.com · claude.com · cursor.com)과
API · 에이전트 도메인은 서로 다릅니다.
브라우저로 grok.com이 열려도 CLI가 안 될 수 있고, 그 반대도 있습니다.
게이트웨이를 쓸 때도 웹 UI 허용 ≠ API 게이트웨이 허용을 따로 확인하세요.
4-4. 원격 개발 — 하네스는 B, A는 접속·동기화만
코드와 grok / agent를 모델 egress가 되는 B에 두고, A는 창구만 담당합니다.
- SSH + 원격 IDE (VS Code / Cursor Remote SSH, JetBrains Gateway 등)
gitpush/pull,rsync, SSHFS, 상호 마운트(NFS/SMB), 클라우드 워크스페이스
- 장점 — HTTP/2·SOCKS 미지원 같은 중계 프로토콜 문제를 통째로 회피. B가 "정상 경로"로 모델에 붙는다
- 단점 — 개발 체감 지연. 시크릿·빌드 캐시가 B에 쌓임. 그리고 Cursor 공식 안내처럼 Remote SSH에서도 일부 AI 기능은 로컬 머신이 모델과 통신하는 제품이 있어, "파일만 원격, AI는 로컬"이면 로컬 egress가 다시 필요해질 수 있음 — 제품별 확인 필수
- 보안 — B의 디스크·로그·
auth.json보호, 공유 VM이면 멀티테넌트 격리
4-5. 메시지 큐 · 중계 봇 (저대역 · 반수동)
A↔B가 채팅·이슈·파일 드롭으로 프롬프트와 패치만 교환하고, 모델 호출은 B만 합니다.
- 장점 — A에 아웃바운드가 거의 없어도 됨. 에어갭에 가장 가까운 형태
- 단점 — 왕복이 사람/봇 속도라 수십 턴짜리 도구 루프와 맞지 않음. 패치에 키가 섞여 나가는 사고 위험
- 실무에서는 비상·리뷰 전달용이지, 대화형 에이전트를 대체하기는 어렵습니다
4-6. 패턴 비교 요약
| 패턴 | 자동화 | 지연 | 구현 난이도 | 정책 친화 | 비고 |
|---|---|---|---|---|---|
SSH SOCKS / -L | 높음 | 중 | 낮~중 | 점프호스트 허용 시 | Claude Code는 SOCKS 비호환 |
| 기업 HTTPS 프록시 | 높음 | 중 | 중 (인증·CA) | 가장 정석 | HTTP/2 이슈 대비 필요 |
| API 게이트웨이 | 높음 | 중 | 중~높 | 정석 | 프로토콜 호환이 관건 |
| 원격 개발 (하네스가 B) | 높음 | 체감 큼 | 중 | 정석 | 제품별 "AI는 로컬" 예외 주의 |
| 큐 · 봇 | 낮음 | 큼 | 낮음 | 에어갭 | 도구 루프에 부적합 |
5. S2 · S3 시나리오
2장의 S1을 기준선으로 두고, 실제로 쓸 만한 두 가지 구성을 흐름도로 봅니다. 차이는 딱 하나 — "도구 실행이 어디서 일어나는가"입니다.
5-1. S2 — 하네스는 A, 추론 트래픽만 B로
- 클라이언트가 HTTP(S) 프록시(또는 지원되는 SOCKS)를 실제로 따를 것
- 장시간 스트림이 프록시에서 죽지 않을 것 (SSL 재서명 + HTTP/2 조합이 특히 위험)
- Claude Code라면 SOCKS 대신 HTTP 프록시 또는
ANTHROPIC_BASE_URL게이트웨이
5-2. S3 — 하네스·워크스페이스를 B로, A는 접속·동기화만
- B가 모델 도메인으로 정상 egress 할 것
- 제품이 "원격 호스트에서 에이전트 실행"을 지원하거나, 최소한 SSH 세션 안에서 CLI를 돌릴 수 있을 것
- Remote SSH 계열은 일부 AI 기능이 로컬에서 모델과 통신할 수 있으므로, "IDE 통합"보다 B의 터미널에서 CLI를 직접 실행하는 쪽이 예측 가능함
- 코드·시크릿이 A에 남는다
- 큰 레포·GPU·연결 장비를 그대로 쓴다
- 대신 프로토콜(스트리밍·SOCKS·HTTP/2)과 싸워야 한다
- 프로토콜 문제는 사라진다 (B가 정상 경로)
- 대신 코드·빌드 캐시·시크릿이 B로 이사한다
- 편집 체감 지연과 B의 격리·백업이 새 숙제
6. Grok Build vs Cursor CLI — 중계 시 어디를 뚫나
공개 문서와 일반 아키텍처 수준의 정리입니다. 두 제품 모두 하네스는 로컬이라는 점은 같고, 모델 쪽에 붙는 방식이 다릅니다 — 그래서 "중계로 뚫어야 할 지점"도 달라집니다.
6-1. Grok Build (grok)
- 로컬 바이너리 — Rust 하네스(TUI / headless
-p/ ACP). 도구·워크스페이스·세션은 로컬(~/.grok/등) - 호스티드 — 세션(OAuth
auth.x.ai/ grok.com) 또는XAI_API_KEY→ 공개 추론https://api.x.ai - 엔터프라이즈 · 커스텀 —
base_url,GROK_MODELS_BASE_URL,GROK_CLI_CHAT_PROXY_BASE_URL/[endpoints] cli_chat_proxy_base_url등으로 자체 프록시·게이트웨이에 붙일 수 있음(문서화됨) - 로컬 추론 —
base_url = http://127.0.0.1:11434/v1식이면 모델 egress 자체가 불필요해짐(하네스만 로컬로 동작)
- 허용된 HTTPS 프록시 · 배스천으로
api.x.ai(로그인 시auth.x.ai/ grok.com)에 도달, 또는 - 기업 chat / inference proxy URL로 CLI 엔드포인트를 재지정, 또는
- 하네스를 아예 B에서 실행(원격 개발)
6-2. Cursor CLI (agent) · IDE
- 로컬 —
agent프로세스 + 워크스페이스 도구. ACP는 stdio JSON-RPC로 에디터에 임베드 - 원격 — Cursor 백엔드가 모델 라우팅과 에이전트 프로토콜을 소유. 공식 엔드포인트 예:
https://api2.cursor.sh— 다수 API (CLI-e예시)https://api5.cursor.sh— 에이전트. 포럼·이슈에서agentn.*.api5.cursor.sh같은 리전 호스트가 언급되지만 정확한 서브도메인은 버전·리전에 따라 변할 수 있음(추정 영역)- 보조:
api3.cursor.sh,repo42.cursor.sh, CDN·마켓플레이스 도메인
- 프록시 —
HTTP(S)_PROXY+ 필요 시 HTTP/1.1 에이전트 모드, TLS 검사 CA - 중계 시 뚫을 지점 —
*.cursor.sh(최소api2/api5)와 인증·CDN allowlist. "OpenAI 호환 리버스 프록시 하나"로 끝내기는 어렵고, Cursor가 요구하는 도메인과 스트림 특성을 그대로 통과시키는 쪽이 정석 - Cloud Agents API(
api.cursor.com) — 클라우드에서 리포를 돌리는 다른 축. 로컬 차단 환경의 "A 하네스 중계"와 혼동하지 말 것
6-3. 한눈에 비교
| 항목 | Grok Build | Cursor CLI |
|---|---|---|
| 하네스 공개·문서화 | 하네스 소스와 커스텀 base_url 경로가 상대적으로 명확 | 에이전트 프로토콜이 제품 백엔드 중심 |
| 모델 키 | 사용자·팀 xAI 키 또는 세션 | Cursor 계정 / API 키, 모델은 라우터가 배분 |
| 중계 친화성 | 게이트웨이·로컬 모델로 엔드포인트 치환이 쉬움 | 공식 도메인 allowlist + HTTP 프록시가 주 경로 |
| 로컬 도구 | 동일 — 로컬(또는 원격 워크스페이스)에서 실행 | |
7. 보안 · 컴플라이언스
중계는 홉을 하나 더 만드는 일입니다. 홉이 늘면 자격증명이 놓이는 자리, 로그가 남는 자리, 데이터가 머무는 자리가 함께 늘어납니다.
- 자격증명 —
~/.grok/auth.json, Cursor 토큰,XAI_API_KEY/CURSOR_API_KEY/ Anthropic 키를 터널·티켓·채팅에 복사하지 말 것. 게이트웨이에는 게이트웨이 전용 키를 두고, 업스트림 키는 B에만 둔다 - 데이터 유출 — 프롬프트에는 소스·시크릿·고객 데이터가 실린다. 중계 홉(B · 기업 프록시 · LLM Gateway)마다 보존 기간 · 지역 · 학습 사용 여부를 계약과 설정으로 확인한다
- 우회 vs 허용된 프록시 — 방화벽 정책을 깨는 개인 VPN·비승인 SOCKS는 감사·징계 대상이 될 수 있다. 승인된 egress proxy · bastion · VDI · 원격 개발 호스트를 쓰는 구성이 안전한 프레임이다
- 감사 로그 — SSH 세션 로그, 프록시 access log, 게이트웨이의 프롬프트/응답 메타데이터, IdP 로그인. 스트리밍 본문까지 로깅하는 것은 민감하므로 보통 메타만 남긴다
- TLS 검사 — 재서명 프록시는 HTTP/2 · 인증서 고정 · 장시간 SSE와 충돌한다. 벤더 권고는 해당 도메인에 대한 inspection bypass인 경우가 많다(Cursor 문서 등)
- 공급망 — B가 도구로
curl | sh를 하거나 임의 도메인에 나가면 이미 "모델만 중계" 범위를 넘어선다. B에도 egress 정책과 샌드박스가 필요하다
8. 선택 가이드 · 한 줄 요약
8-1. 결정 트리
- A에 큰 레포 · GPU · 물리 디바이스가 붙어 있으면 → S2 우선
- 프로토콜·프록시와 싸울 바에는 → S3
- 에어갭에 가까우면 → 큐/봇 또는 S3 + 엄격한 B egress 정책
8-2. 한 줄 요약
- 하네스 = 로컬 도구 루프 — 컨텍스트 조립 · 도구 디스패치 · 권한 · 세션. 파일과 셸은 전부 여기서 움직인다
- 모델 = 원격 추론 — HTTPS / HTTP2 / Connect-RPC로 나가는 한 줄기 트래픽. 막히는 곳은 사실상 이 한 지점뿐
- S1 — A가 직접 나갈 수 있으면 8단계 정상 루프
- S2 — A가 못 나가면, 승인된 HTTPS 프록시 · 배스천 · 게이트웨이로 추론만 중계한다. 코드·도구는 A에 남는다
- S3 — 프로토콜(SOCKS 미지원 · HTTP/2 스트림)이 말썽이면 하네스째로 B로 옮기고 A는 원격 개발 채널만 쓴다
- 제품 차이 — Cursor는 공식
*.cursor.sh도메인을 통과시키는 게 핵심, Grok은api.x.ai도달 또는 커스텀base_url치환이 핵심 - 선을 지킬 것 — 우회가 아니라 승인된 경로를 쓴다. 홉이 늘면 키·로그·데이터가 남는 자리도 늘어난다
8-3. 참고 키워드 · 출처
ssh -D / -L / -R · reverse tunnel · egress proxy · forward vs reverse proxy ·
PAC / WPAD · jump host · bastion · air-gapped + jump · LLM Gateway ·
HTTPS_PROXY / NO_PROXY · ANTHROPIC_BASE_URL ·
GROK_CLI_CHAT_PROXY_BASE_URL · base_url(Grok custom models) ·
Cursor agent CLI · api2.cursor.sh · api5.cursor.sh · api.x.ai ·
Connect-RPC / HTTP2 streaming · ACP(Agent Client Protocol) · Remote SSH · rsync · SSHFS · zero data retention
출처(조사 시점 공개 문서 기준) — xAI Docs(REST base https://api.x.ai, Quickstart, Responses API) ·
Grok Build user guide(Authentication, Custom Models, GROK_CLI_CHAT_PROXY_BASE_URL, endpoints) ·
Cursor Docs(Network Configuration, CLI proxy / useHttp1ForAgent, ACP agent -e https://api2.cursor.sh) ·
Claude Code Docs(Enterprise network config — HTTPS proxy, SOCKS 미지원, host allowlist, ANTHROPIC_BASE_URL).
커뮤니티·리버스엔지니어링 글에 등장하는 호스트명은 참고용이며 공식 allowlist를 우선합니다.