코딩 에이전트를 로컬 서버로 다시 짓다: anomalyco/opencode v2.0.32의 백그라운드 서비스·권한 규칙·1.x→2.x 전환 심층 해부

“오픈소스 코딩 에이전트”라는 한 줄 설명으로 21만 스타를 모은 anomalyco/opencode가 오늘(2026-10-19) GitHub Trending 전체 일간 3위(오늘 +1,414 stars), TypeScript 일간 1위에 올랐다. 겉보기엔 익숙한 터미널 에이전트지만, 지금 저장소 안에서는 꽤 큰 공사가 진행 중이다. 기본 브랜치 dev의 루트 package.json은 이미 2.0.32이고, 배포 채널도 1.x(opencode-ai)와 2.x(@opencode/cli)로 갈라졌다. 2.x의 핵심은 “에이전트를 TUI 프로그램이 아니라 로컬 서버로 다시 짓는 것”이다. TUI·데스크톱·웹·에디터(ACP)는 모두 같은 HTTP API를 쓰는 손님이 되고, 세션·권한·도구 실행·터미널은 백그라운드 서비스가 소유한다.

이 글은 기능 소개를 넘어 실무자가 도입 전에 알아야 할 세 가지를 따진다. ① 2.x 모노레포가 어떤 층으로 나뉘고 서버·서비스 모델이 실제로 어떻게 뜨는지, ② 권한(permission) 규칙이 어떻게 평가되고 plan 에이전트의 “읽기 전용”이 어디까지인지, ③ 1.x→2.x 전환에서 무엇이 바뀌고 무엇을 조심해야 하는지. 그리고 박스(리눅스 VM)에서 npm 공식 바이너리 v2.0.32를 격리된 HOME으로 띄우고, 로그인·API 키 없이 로컬 모의(mock) LLM 서버를 붙여 서버 기동, 인증, 도구 호출, 권한 거절까지 직접 재 봤다. 모든 수치는 2026-10-19 16:55~17:06 KST 기준 실측이거나 저장소·레지스트리에서 확인한 값이다.

한눈에 보기: 오늘 기준 스냅숏

왜 지금 트렌딩인가: 메이저 전환 한가운데

OpenCode는 오래전부터 상위권 저장소였지만, 최근 2주 릴리스 노트를 보면 “2.x를 기본값으로 밀어 올리는” 작업이 몰려 있다. 같은 날 Trending에는 cursor/plugins(#4), ruflo(#5), ai-memory(#6), stablyai/orca(#8)처럼 에이전트 하네스·플러그인·메모리 저장소가 몰려 있어, 그 중심에 있는 “에이전트 본체”에 관심이 다시 쏠린 측면도 있다.

1.x와 2.x: 무엇이 달라졌나

저장소 구조: 계층이 엄격한 모노레포

루트 packages/ 아래 패키지가 40개가 넘고, TS/TSX 파일만 약 5천 개다. 큰 덩어리는 아래와 같다(파일 수는 *.ts/*.tsx 기준, 얕은 클론에서 직접 셈).

AGENTS.md가 못 박은 규칙이 구조를 잘 설명한다. 런타임 의존은 Schema → Core·Protocol → Server 방향으로만 흐르고, Client 런타임 코드는 Schema·Protocol에만 기대며 Core·Server를 절대 가져오지 않는다. SDK가 Client·Core·Server를 조합한다. 공개 Protocol이나 Server의 HttpApi를 바꾸면 packages/client에서 bun run generate로 클라이언트를 재생성해야 하고 생성 파일은 직접 고치지 않는다. 즉 API 계약이 먼저, 화면은 나중인 구조이고, TUI도 이 계약을 쓰는 하나의 클라이언트일 뿐이다.

서버·서비스 모델은 어떻게 뜨나

packages/cli/src/server-process.ts를 보면 서버는 세 가지 모드(default·service·stdio)로 뜬다. 공통으로 호스트 기본값은 127.0.0.1이고, 비밀번호는 서비스 모드면 저장된 값 또는 새 난수, 나머지는 OPENCODE_PASSWORD/OPENCODE_SERVER_PASSWORD 환경변수나 새 난수다. stdio 모드에서는 이 비밀번호 환경변수를 지워 도구가 상속하지 못하게 한다. 인증은 사용자명 opencode 고정의 HTTP Basic이다.

# 서비스 상태·중지 (서비스는 사용자 단위로 하나)
opencode service status        # → http://127.0.0.1:49374
opencode service stop

# 전용 서버를 명시 비밀번호로 띄우고 API 직접 호출
OPENCODE_SERVER_PASSWORD='<긴 난수>' opencode serve --port 4096
curl -u opencode:'<긴 난수>' http://127.0.0.1:4096/api/info
OPENCODE_PASSWORD='<긴 난수>' opencode api --server http://127.0.0.1:4096 server.info

이 구조 덕분에 TUI를 닫아도 세션과 PTY가 서비스에 남고, 데스크톱·웹·휴대폰(페어링)이 같은 세션을 이어 볼 수 있다. 서버를 재시작할 때 PTY를 넘기는 OPENCODE_PTY_HANDOFF 경로도 코드에 있다. 반대로 말하면 “에이전트를 끈다”의 의미가 TUI 종료가 아니라 서비스 중지로 바뀐 것이다.

에이전트와 도구: 루프 안에 무엇이 들어가나

기본 에이전트는 build(전체 권한, 기본값)와 plan(읽기 전용 지향) 두 개이고, 서브에이전트로 general과 explore가 있다. 숨은 에이전트 title·summary·compaction은 제목 생성·요약·컨텍스트 압축 전용이다. 모의 LLM으로 받아 본 실제 요청을 보면 build 에이전트는 매 턴 도구 12개를 스키마로 싣는다.

권한 규칙: ‘마지막 일치’와 ask의 의미

packages/core/src/permission.ts의 evaluate()는 규칙 배열을 합친 뒤 action·resource 와일드카드가 맞는 마지막 규칙을 고른다(findLast). 아무 규칙도 맞지 않으면 기본값은 ask다. 그래서 에이전트 정의가 앞에 깔고, 사용자 설정·프로젝트별 저장 승인(saved, effect allow)이 뒤에서 덮어쓰는 구조가 된다. plan 에이전트가 “edit 전부 deny → plan 디렉터리만 allow” 순서로 규칙을 넣는 이유도 이것이다.

박스 스모크 테스트: 로그인 없이 모의 LLM으로

실제 모델을 쓰지 않고도 서버·에이전트 루프·권한 경계를 확인하려고, OpenAI 호환 /v1/chat/completions SSE를 흉내 내는 70줄짜리 파이썬 서버를 127.0.0.1:18080에 띄웠다. 이 서버는 요청을 JSONL로 기록하고, 환경변수로 지정한 도구 호출 하나를 돌려준 뒤 도구 결과가 오면 “MOCK_OK”로 끝낸다. OpenCode에는 문서의 커스텀 제공자 형식(@ai-sdk/openai-compatible + baseURL)으로 연결했다.

# 격리 환경 (실제 실행한 값)
export HOME=$PWD/smoke/home XDG_CONFIG_HOME=$HOME/.config XDG_DATA_HOME=$HOME/.local/share
export OPENCODE_DISABLE_AUTOUPDATE=1 OPENCODE_DISABLE_MODELS_FETCH=1 DO_NOT_TRACK=1
unset OPENAI_API_KEY ANTHROPIC_API_KEY OTEL_EXPORTER_OTLP_ENDPOINT

# 공식 npm 플랫폼 패키지에서 바이너리만 추출 (integrity sha512 일치 확인)
curl -sLO https://registry.npmjs.org/@opencode/cli-linux-x64/-/cli-linux-x64-2.0.32.tgz
tar xzf cli-linux-x64-2.0.32.tgz && ./package/bin/opencode --version   # opencode v2.0.32

# ~/.config/opencode/opencode.json
{
  "model": "mock/mock-coder",
  "provider": {
    "mock": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://127.0.0.1:18080/v1", "apiKey": "dummy" },
      "models": { "mock-coder": { "name": "Mock Coder", "tool_call": true } }
    }
  }
}

# 비대화형 한 턴 (stdin을 반드시 닫을 것)
opencode run --standalone "do the task" < /dev/null
opencode run --standalone --agent plan "do the task" < /dev/null

신뢰 경계 정리

CI·헤드리스 운영 레시피

# 1) 버전 고정 설치
npm i -g @opencode/cli@2.0.32

# 2) 보수적 권한: shell·edit는 ask → 비대화형에서는 자동 거절
cat > opencode.json <<'EOF'
{ "permission": { "bash": "ask", "edit": "ask" } }
EOF

# 3) 전용 서버로 한 턴, JSON 이벤트 출력, stdin 닫기
opencode run --standalone --format json --agent plan \
  "이 저장소의 테스트 구조를 요약해 줘" < /dev/null > result.jsonl

# 4) 정말 수정이 필요한 잡만 명시적으로 --auto (컨테이너 안에서)
opencode run --standalone --auto "lint 오류를 고쳐 줘" < /dev/null

# 5) 공용 러너 정리
opencode service stop || true

여기서 bash: ask는 이번 스모크에서 shell 거절로 직접 확인한 설정이고, edit: ask는 같은 규칙 체계를 따르지만 이번에는 따로 재지 않았다. 핵심은 “비대화형에서 ask = 거절”이라는 성질을 이용해 기본은 읽기만 하는 잡, 쓰기가 필요한 잡만 컨테이너 안에서 –auto로 나누는 것이다.

비슷한 도구와 비교

OpenCode의 차별점은 모델 중립성과 “에이전트 = 문서화된 API를 가진 로컬 서버”라는 구조다. 143개 작업의 OpenAPI가 있다는 건 사내 대시보드·봇·에디터 플러그인이 TUI를 흉내 내지 않고 같은 세션·권한·PTY를 직접 다룰 수 있다는 뜻이다. 대신 OS 수준 샌드박스를 기본 제공하는 도구들과 달리 격리는 사용자의 몫이다.

도입 평가 체크리스트

트레이드오프와 주의점

누가 쓰면 좋은가

정리

OpenCode 2.x는 “터미널에서 도는 에이전트”를 인증된 로컬 API 서버 + 여러 클라이언트로 재구성한 버전이다. 계층을 강제하는 모노레포, 143개 작업의 OpenAPI, 사용자 단위 백그라운드 서비스, 마지막 일치 방식의 권한 규칙이 그 뼈대다. 박스에서 돌려 보니 서버는 228 ms 만에 127.0.0.1에만 떠서 비밀번호 없는 요청을 401로 막았고, 모의 LLM 한 턴은 약 1초, 비대화형 run은 ask 규칙을 자동 거절했다. 반면 plan 에이전트가 shell 리다이렉션으로 파일을 쓰고, build가 프로젝트 밖에도 묻지 않고 쓰며, 일반 명령 한 번에 서비스가 상주하는 것도 확인했다. 공식 문서 말대로 권한은 안내판이지 울타리가 아니다. 구조의 이점은 적극적으로 쓰되, 격리는 컨테이너로, 정책은 ask/deny 규칙으로, 버전은 고정해서 도입하는 것이 지금 시점의 현실적인 사용법이다.