Nats on Yarang's Tech Lair

NATS JetStream으로 멀티-LLM 분산 오케스트레이터 구축하기

Fri, 08 May 2026 21:57:11 +0900

1편에서는 Claude, ZAI, Codex, Gemini 네 가지 AI를 같은 태스크에 동시에 돌리면서 발견한 모델별 제한 사항을 다뤘다. 이번 편은 “어떻게 그게 가능하도록 만들었나”—시스템 설계와 구현 이야기다.

시스템 개요

AgentForge는 세 가지 요소로 이루어진다.

[태스크 발행자]
 │ NATS JetStream publish
 ▼
[NATS 브로커] ─── af.worker.{id}.inbox
 │ JetStream consume (워커별 독립 스트림)
 ▼
[워커 폴러] × N (poller.py × 18개)
 │ LLM CLI 실행 (claude / codex / gemini)
 ▼
[결과 반환] af.task.{task_id}.completed

발행자가 NATS에 태스크를 올리면, 각 워커가 독립적으로 구독하고 있다가 자신의 inbox로 들어온 메시지를 받아 LLM CLI를 실행한다. 결과는 완료 주제로 다시 publish된다.

왜 NATS JetStream인가

메시지 브로커 선택지는 여러 개였다: Redis Streams, Kafka, RabbitMQ, NATS JetStream.

NATS JetStream을 선택한 이유:

단일 바이너리 — 별도의 런타임 없이 nats-server 하나로 동작한다. Kafka의 ZooKeeper나 RabbitMQ의 Erlang/OTP 의존성이 없다.
내장 영속성 — JetStream은 NATS 위에 올라가는 스트리밍 레이어로, 메시지를 파일시스템에 저장한다. 워커가 재시작되어도 처리 안 된 태스크가 유실되지 않는다.
NKey 기반 인증 — 워커별로 독립된 Ed25519 keypair를 발급할 수 있다. 한 워커가 침해되어도 다른 워커의 자격증명은 유효하다.
경량 — 단일 서버에서 메모리 사용량 ~30MB. 18개 워커를 연결해도 브로커 부하가 거의 없다.

핵심: poller.py의 백엔드 어댑터

워커의 핵심은 poller.py다. 이 파일 하나가 NATS 구독, LLM CLI 실행, 결과 반환을 모두 담당한다.

LLM별 실행 방식이 다르기 때문에, 백엔드 어댑터 딕셔너리로 분리했다.

_BACKENDS: dict[str, dict] = {
 "claude": {
 "bin": os.environ.get("CLAUDE_BIN", "/usr/local/bin/claude"),
 "tools": os.environ.get("ALLOWED_TOOLS", "Read,Edit,Write,Glob,Grep"),
 "model": os.environ.get("CLAUDE_MODEL", ""),
 },
 "codex": {
 "bin": os.environ.get("CODEX_BIN", "/usr/bin/codex"),
 "model": os.environ.get("CODEX_MODEL", ""),
 "sandbox": os.environ.get("CODEX_SANDBOX", "read-only"),
 },
 "gemini_cli": {
 "bin": os.environ.get("GEMINI_BIN", "/usr/bin/gemini"),
 "model": os.environ.get("GEMINI_MODEL", ""),
 },
}

MODEL_BACKEND 환경변수로 어떤 LLM을 쓸지 결정한다. 덕분에 동일한 poller.py 코드로 18개 워커가 각자 다른 LLM을 실행한다.

Claude 백엔드

async def run_claude(instructions: str, task_id: str) -> tuple[int, str]:
 cfg = _BACKENDS["claude"]
 cmd = [cfg["bin"], "--print", "--allowedTools", cfg["tools"]]
 if cfg.get("model"):
 cmd += ["--model", cfg["model"]]
 proc = await asyncio.create_subprocess_exec(*cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)

--print 플래그가 핵심이다. Claude Code가 대화 모드가 아닌 비대화형 모드로 실행되어 stdout으로 결과를 반환하게 만든다.

ZAI 백엔드

ZAI는 Anthropic API 호환 엔드포인트를 제공하기 때문에 별도 백엔드가 없다. 환경변수 두 개로 라우팅을 바꾼다.

# /etc/agentforge/cc-zai-high-dev-01.env
ANTHROPIC_BASE_URL=<ZAI endpoint>
ANTHROPIC_AUTH_TOKEN=<ZAI API key>

systemd EnvironmentFile= 지시어로 이 파일을 주입하면, claude 바이너리가 ZAI 엔드포인트로 요청을 보낸다. 코드 변경 없이 환경변수만으로 다른 LLM 공급자를 연결하는 셈이다.

선언적 관리: fleet.yaml × servers.yaml

18개 워커를 수동으로 관리하는 건 비현실적이다. 두 개의 YAML 파일로 전체 인프라를 선언적으로 정의했다.

servers.yaml — 서버 인벤토리

servers:
 - name: worker-node-1
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

 - name: broker-host
 role: broker-host
 services: [nats-jetstream, postgres]

 - name: worker-node-2
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

fleet.yaml — 워커 배치

workers:
 - worker_id: cc-go-dev-01
 llm: claude-code
 model: claude-sonnet-4-6
 lang: go
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: true

 - worker_id: codex-py-dev-01
 llm: codex
 model: gpt-5.5
 lang: python
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

host 필드 하나를 바꾸면 워커가 다른 서버로 이동한다. enabled: false로 설정하면 배포 스크립트가 해당 워커를 중지한다.

워커 템플릿 시스템: provision_worker.py

워커를 새로 추가할 때마다 systemd 유닛 파일을 직접 작성하는 건 오류가 생기기 쉽다. Jinja2 템플릿 + 프로비저닝 스크립트로 자동화했다.

템플릿 구조

templates/
 systemd/
 claude.service.j2 # claude-code, ZAI 공용
 codex.service.j2 # OpenAI Codex
 gemini.service.j2 # Google Gemini CLI

claude.service.j2의 핵심 부분:

Environment=MODEL_BACKEND=claude
Environment=CLAUDE_BIN={{ claude_bin }}
{% if claude_model %}
Environment=CLAUDE_MODEL={{ claude_model }}
{% endif %}
{% if env_file %}
EnvironmentFile={{ env_file }}
{% endif %}
Environment=WORK_BASE={{ work_base }}
Environment=WORK_DIR={{ work_base }}/repo
Environment="{{ 'ALLOWED_TOOLS=' + allowed_tools }}"
Environment=CREATE_PR={{ 'true' if create_pr else 'false' }}
{% if create_pr and github_remote %}
Environment=GITHUB_REMOTE={{ github_remote }}
{% endif %}

ZAI 워커는 env_file 블록이 활성화되어 EnvironmentFile이 추가된다. PR 생성 워커는 github_remote가 주입된다. 나머지는 기본값을 쓴다.

provision_worker.py 사용법

# 미리보기 (실제 배포 없음)
python3 scripts/provision_worker.py --worker new-worker-id --dry-run

# 실제 배포 (NATS creds 발급 포함)
python3 scripts/provision_worker.py --worker new-worker-id --issue-creds

# fleet.yaml 전체 일괄 배포
python3 scripts/provision_worker.py --all

내부적으로 수행하는 작업:

fleet.yaml에서 워커 항목 읽기
servers.yaml에서 대상 호스트 읽기
Jinja2 템플릿 렌더링
SSH로 /etc/systemd/system/{worker_id}-poller.service 배포
워크 디렉터리 생성
systemctl daemon-reload && enable --now
(선택) nsc add user로 NATS NKey 발급 → creds 배포 → auth.conf 재생성

분산 호스트: 두 번째 서버에 워커 추가

모든 워커를 한 서버에서 돌리면 단일 장애점이 된다. 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커에 연결하는 방법은 autossh 터널이다.

[Unit]
Description=NATS 브로커 터널
After=network-online.target

[Service]
ExecStart=/usr/bin/autossh -N \
 -L 4222:127.0.0.1:4222 \
 -i /home/ubuntu/.ssh/id_ed25519 \
 broker-host
Restart=always
RestartSec=10

이 설정이 활성화된 상태에서 워커는 항상 nats://127.0.0.1:4222로 연결한다. 브로커 호스트 주소를 몰라도 된다. 터널만 살아있으면 어느 호스트에서든 동일하게 동작한다.

NATS 자격증명 운영 경험

구현 중 가장 복잡했던 부분은 NATS NKey 관리다.

NATS JetStream의 인증 구조는 계층적이다.

Operator (최상위 서명 기관)
 └── Account: SYS (시스템 계정)
 └── Account: Services (워커 계정)
 ├── User: cc-dev-01
 ├── User: cc-go-dev-01
 ├── User: codex-py-dev-01
 └── ...

각 워커는 독립된 User NKey를 가지고, Services 계정의 권한 범위(af.>, _INBOX.>, $JS.>) 내에서만 publish/subscribe할 수 있다.

신규 워커를 추가할 때 Operator의 signing key가 필요하다. 초기에 이 키의 백업을 만들지 않았다가 분실하는 사고가 있었다. 결과적으로 Operator를 전부 재생성하고 모든 워커의 creds를 일괄 교체했다. 서비스 다운타임은 약 60초.

# 재생성 절차
nsc add operator AgentForge
nsc add account SYS
nsc add account Services
for worker in cc-dev-01 cc-go-dev-01 ...; do
 nsc add user --account Services --name $worker \
 --allow-pub "af.>,_INBOX.>,$JS.>" \
 --allow-sub "af.>,_INBOX.>,$JS.>"
done
nsc generate config --mem-resolver --sys-account SYS > auth.new.conf

새 워커 추가: 전체 절차

이 시스템이 완성된 이후 새 워커를 추가하는 절차는 단순하다.

1단계: fleet.yaml에 항목 추가

- worker_id: my-new-worker
 llm: claude-code
 model: claude-haiku-4-5
 lang: multi
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

2단계: 미리보기

python3 scripts/provision_worker.py --worker my-new-worker --dry-run

3단계: 실제 배포

python3 scripts/provision_worker.py --worker my-new-worker --issue-creds

끝이다. 템플릿 렌더링, SSH 배포, NATS 자격증명 발급, 서비스 등록까지 한 명령으로 처리된다.

다음 단계

현재 시스템은 워커가 태스크를 독립적으로 처리하는 구조다. 앞으로 만들고 싶은 것:

라우팅 정책: 태스크 특성에 따라 적합한 워커를 자동 선택 (Go 코드 → claude-go-dev, 비용 최우선 → ZAI 경량 티어)
결과 비교 대시보드: fan-out 결과를 나란히 보여주는 UI
비용 추적: 워커별 API 호출 비용 집계

코드는 GitHub에 공개되어 있다.

4개의 AI에게 같은 코딩 태스크를 동시에 보내봤다

Fri, 08 May 2026 21:55:39 +0900

같은 버그 수정 태스크를 Claude, ZAI(GLM), OpenAI Codex, Google Gemini에게 동시에 던지면 어떤 일이 벌어질까?

이 질문에서 AgentForge 프로젝트가 시작됐다. 여러 LLM CLI를 NATS JetStream 메시지 큐로 묶어서 같은 태스크를 병렬로 처리하는 시스템을 만들었고, 그 과정에서 예상치 못한 발견들이 있었다. 이번 글은 “설정하면서 뭘 발견했나"에 집중한 비교 실험 기록이다.

시스템의 설계·구현 이야기는 2편에서 다룬다.

테스트한 AI 목록

최종적으로 운영 중인 워커 18개의 구성은 다음과 같다.

계열	모델	비고
Claude Code	claude-sonnet-4-6	메인 개발 워커
Claude Code	claude-sonnet-4-5	이전 세대 비교용
Claude Code	claude-haiku-4-5	경량·고속
Claude Code	claude-opus-4-6	최고 사양
Claude Code	claude-opus-4-5	이전 세대 비교용
ZAI (GLM)	glm-5.1	고사양 티어
ZAI (GLM)	glm-4.7	중간 티어
ZAI (GLM)	glm-4.5-air	경량 티어
OpenAI Codex	gpt-5.5
Codex	gpt-5.4	1M 컨텍스트
Codex	gpt-5.4-mini	400K 컨텍스트
Codex	gpt-5.3-codex	272K 컨텍스트
Google Gemini	gemini-2.5-flash
Gemini	gemini-2.5-pro	고사양
Gemini	gemini-2.5-flash-lite	경량

처음 시작할 때 목록은 훨씬 짧았다. 어떤 모델을 쓸 수 있는지 직접 실험해보면서 늘어났다.

발견 1: Claude 3.x 시리즈는 이미 접근 불가

Claude Code를 오래 써온 사람이라면 Claude 3.7 Sonnet, 3.5 Sonnet, 3.5 Haiku를 떠올릴 수 있다. 그래서 이 모델들도 워커로 추가하려 했다.

claude --model claude-3-7-sonnet-20250219 --print "hello"
# → "may not exist or no access"

세 모델 모두 동일한 오류. Claude 3 시리즈는 2026년 초에 EOL을 맞이했고, Claude Code CLI를 통한 접근이 차단됐다. 현재 Claude Code 구독으로 쓸 수 있는 것은 4.x 계열뿐이다.

결론: Claude 워커는 4.5/4.6 계열로만 구성했다.

발견 2: ChatGPT 계정 Codex는 모델 선택이 제한적이다

OpenAI Codex CLI는 ChatGPT Plus/Pro 계정이나 별도 API 키로 인증한다. ChatGPT 계정 기반일 경우 접근 가능한 모델이 제한된다.

codex --model gpt-5.5-pro "fix the bug"
# → "Model gpt-5.5-pro is not supported with ChatGPT account"

codex --model gpt-5.5 "fix the bug"
# → 정상 작동

ChatGPT 계정으로 사용할 수 있는 모델:

모델	컨텍스트	추론 수준
gpt-5.5	1M / 1M	High
gpt-5.4	1M / 1M	Medium
gpt-5.4-mini	400K / 400K	Medium
gpt-5.3-codex	272K / 400K	Medium

gpt-5.5-pro를 포함한 다른 모델은 모두 “not supported with ChatGPT account” 오류를 반환한다. API 키 방식이라면 더 많은 모델을 쓸 수 있지만, 그건 다른 접근 방식이다.

발견 3: Gemini CLI는 2.5 시리즈만 된다

Gemini CLI(gemini 바이너리)로 여러 모델을 테스트했다.

gemini -p "hello" -m gemini-2.0-flash
# → ModelNotFoundError: models/gemini-2.0-flash is not found

gemini -p "hello" -m gemini-1.5-pro
# → ModelNotFoundError

gemini -p "hello" -m gemini-2.5-flash
# → 정상 작동

현재 계정으로 접근 가능한 Gemini 모델:

gemini-2.5-flash — 기본 추천 모델
gemini-2.5-pro — 고사양
gemini-2.5-flash-lite — 경량

Gemini 2.0 이하 버전은 ModelNotFoundError를 반환한다. 계정 플랜이나 API 키 종류에 따라 다를 수 있지만, Gemini CLI 기준으로는 2.5 시리즈만 안정적으로 동작했다.

발견 4: ZAI는 Claude SDK로 우회할 수 있다

ZAI는 Anthropic API와 호환되는 엔드포인트를 제공하는 서비스다. 덕분에 Claude Code CLI에서 환경변수 두 개만 바꿔서 GLM 모델을 쓸 수 있다.

ANTHROPIC_BASE_URL=https://<ZAI endpoint> \
ANTHROPIC_AUTH_TOKEN=<ZAI_KEY> \
claude --model glm-5.1 --print "fix the bug"

Claude Code가 내부적으로 Anthropic Python SDK를 쓰기 때문에, ANTHROPIC_BASE_URL만 오버라이드하면 동일한 포맷으로 ZAI의 GLM 모델을 호출한다. 별도의 어댑터 코드 없이 기존 claude 백엔드를 그대로 재사용할 수 있다는 점이 흥미로웠다.

사용한 GLM 모델 3종:

glm-5.1 — 고사양 티어
glm-4.7 — 비용·성능 균형점
glm-4.5-air — 경량·고속

4-way Fan-out 비교 테스트

18개 워커 중 대표 4개(Claude Sonnet, GLM-5.1, Codex gpt-5.5, Gemini 2.5 Flash)에 동일한 Go 버그 수정 태스크를 동시에 발행했다.

태스크: "fix the off-by-one error in the binary search function"

응답 시간 (wall clock):

워커	모델	응답 시간
cc-go-dev-01	claude-sonnet-4-6	~8초
cc-zai-high-dev-01	glm-5.1	~12초
codex-py-dev-01	gpt-5.5	~15초
gemini-py-dev-01	gemini-2.5-flash	~10초

응답 시간보다 흥미로운 건 접근 방식의 차이다. Claude는 함수 전체를 리팩토링하는 경향이 있었고, Gemini는 최소한의 수정을 선호했다. Codex는 테스트 코드까지 함께 추가하는 경우가 많았다.

물론 이건 단일 태스크 결과라 통계적 의미는 없다. 벤치마크가 아니라 “실제로 동작하는지 확인"하는 수준의 검증이었다.

분산 워커: 두 번째 호스트 추가

워커들이 모두 한 서버에 있으면 비교 실험의 의미가 약해진다. 그래서 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커(첫 번째 호스트)에 접근하는 방법은 autossh 터널이다.

[Service]
ExecStart=autossh -N -L 4222:127.0.0.1:4222 broker-host

로컬의 4222 포트를 브로커로 포워딩하면 워커 코드 변경 없이 어느 호스트에서나 nats://127.0.0.1:4222로 접속할 수 있다.

이 방식의 장점: 워커는 브로커가 어디 있는지 알 필요가 없다. 항상 localhost:4222로 연결하면 된다.

운영하면서 가장 당황했던 순간

가장 곤혹스러운 상황은 NATS operator signing key를 분실한 것이었다. NATS JetStream은 NKey 기반 인증을 쓰는데, 신규 워커의 credentials를 발급하려면 operator/account의 signing key(nsc seed)가 필요하다.

nsc add user --account Services --name new-worker
# → "signing key not found"

백업이 없었다. 결국 NATS operator를 통째로 재생성하고, 모든 워커의 credentials를 새 권한 트리로 교체하는 대규모 컷오버를 진행했다. 서비스 다운타임은 약 60초였다.

교훈: NATS operator seed는 생성 즉시 오프라인 백업을 만들어라. 분실하면 재생성 외에 방법이 없다.

정리

이번 실험에서 얻은 실용적인 결론:

Claude 3.x는 EOL - 2026년 기준 Claude Code CLI에서 접근 불가. 4.x만 쓸 것.
Codex ChatGPT 계정은 모델 4종만 - gpt-5.5, 5.4, 5.4-mini, 5.3-codex. Pro 모델은 별도 API 키 필요.
Gemini는 2.5 시리즈만 - CLI 기준 이전 버전 접근 불가.
ZAI는 Claude SDK 환경변수 오버라이드로 통합 가능 - 별도 어댑터 불필요.
NATS NKey는 반드시 백업 - signing key 분실 = 전체 재발급.

다음 편에서는 이 워커들이 어떻게 연결되는지, 시스템 설계와 구현을 다룬다.