Engineering & Tech

Claude Code, 터미널에만 가둬두기 아깝잖아요? API로 꺼내봅시다 (feat. Koine)

Claude Code를 CLI가 아닌 API로 활용하는 방법, 오픈소스 Koine을 통해 도커 기반의 에이전트 서버를 구축하고 TypeScript SDK로 제어하는 가이드를 소개합니다.

김영태

테크리드

안녕하세요. 풀링포레스트 테크리드 김영태입니다.

요즘 개발자들 사이에서 Claude Code가 정말 핫하죠? 저도 처음에 써보고 솔직히 좀 놀랐습니다. 단순히 코드를 짜주는 걸 넘어서, 터미널 명령어를 직접 실행하고 파일을 읽고 쓰면서 '진짜 동료'처럼 일하더군요.

그런데 막상 이걸 우리 팀의 내부 서비스나 자동화 파이프라인에 녹이려고 하니 턱 막히는 부분이 있었습니다. Claude Code는 기본적으로 CLI(Command Line Interface) 도구잖아요. 이걸 백엔드 코드에서 호출하려면 자식 프로세스(Child Process)를 띄우고, 입출력을 파이핑(Piping)하고... 생각만 해도 머리가 지끈거리는 '삽질'의 향기가 났습니다.

"아, 이거 그냥 API처럼 호출해서 쓸 수 있으면 얼마나 좋을까?"

이런 고민을 하던 찰나에 재미있는 오픈소스 프로젝트를 발견해서 공유해보려 합니다. 바로 Koine(코이네)라는 녀석입니다.

왜 그냥 API를 쓰면 안 되나요?

먼저, 이런 의문이 들 수 있습니다. "그냥 Anthropic API 쓰면 되는 거 아냐?"

맞아요. 하지만 일반적인 LLM API는 '텍스트 입력 -> 텍스트 출력' 구조입니다. 만약 AI가 파일을 수정하거나 터미널 명령을 실행하게 하려면, 우리가 직접 그 기능을 구현하고 '도구 호출(Tool Calling)' 루프를 직접 짜야 합니다. 소위 말하는 에이전트 오케스트레이션(Agent Orchestration) 계층을 직접 만들어야 한다는 거죠. 이게 꽤나 번거롭고 실수하기 딱 좋은 작업입니다.

반면 Claude Code는 이 에이전트 루프가 이미 내장되어 있습니다. Anthropic이 갈고닦은 '일 잘하는 로직'이 들어있는 거죠. 우리는 이 로직을 그대로 가져다 쓰고 싶을 뿐입니다.

Koine: 터미널 밖으로 나온 Claude Code

Koine은 고대 그리스어로 '공통어'라는 뜻이랍니다. 이름처럼 애플리케이션과 Claude Code를 이어주는 다리 역할을 합니다. 쉽게 말해, Claude Code CLI를 Docker 컨테이너에 가두고, 이를 제어할 수 있는 HTTP API(REST)를 제공해주는 게이트웨이입니다.

이게 왜 물건이냐면, 더 이상 복잡한 프로세스 관리를 할 필요 없이 `curl`이나 SDK로 편하게 요청만 보내면 되기 때문입니다.

찍먹해보기: 5분 만에 띄우는 나만의 코딩 에이전트 서버

백문이 불여일타(一打)죠. 바로 띄워봅시다. Docker만 있으면 됩니다.

# Docker로 Koine 게이트웨이 실행
docker run -d -p 3100:3100 \
  -e CLAUDE_CODE_GATEWAY_API_KEY=my-secret-key \
  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
  ghcr.io/pattern-zones-co/koine:latest

이제 우리 로컬 3100번 포트에 Claude Code가 대기 중입니다. 이걸 어떻게 써먹을까요? 풀링포레스트에서 주로 쓰는 TypeScript로 예제를 짜봤습니다.

import { createKoine } from '@patternzones/koine-sdk';

// SDK 초기화
const koine = createKoine({
  baseUrl: 'http://localhost:3100',
  authKey: 'my-secret-key',
});

async function askAgent() {
  console.log("에이전트에게 작업 요청 중...");
  
  // 텍스트 생성 요청 (단순 대화뿐만 아니라 파일 조작도 가능)
  const result = await koine.generateText({
    prompt: '현재 디렉토리의 파일 목록을 확인하고, README.md가 없다면 간단하게 만들어줘.'
  });

  console.log("결과:", result.text);
}

askAgent();

보시다시피 아주 직관적입니다. 만약 일반 API였다면 파일 시스템 접근 권한을 주고, 함수를 정의하고 난리를 쳤겠지만, 여기선 Claude Code가 알아서 처리합니다. 심지어 구조화된 출력(Structured Output)도 지원해서 Zod 스키마를 던져주면 JSON으로 예쁘게 받아올 수도 있습니다. 데이터 파이프라인 짤 때 정말 요긴하겠죠.

현업 적용 시 주의할 점 (feat. 보안)

물론, "와 좋다!" 하고 바로 운영 서버에 올리면 곤란합니다. 제가 테크리드로서 항상 팀원들에게 강조하는 부분이기도 한데요, 편리함에는 대가가 따릅니다.

Koine을 통해 실행되는 Claude Code는 컨테이너 내부의 파일 시스템과 쉘에 대한 전체 접근 권한을 가집니다. 즉, 누군가 악의적인 프롬프트를 보내면 컨테이너를 망가뜨리거나 채굴기를 돌릴 수도 있다는 뜻입니다.

네트워크 격리: 절대로, 절대 공용 인터넷(Public Internet)에 이 포트를 노출하지 마세요. VPN 내부나 Docker 네트워크 안에서만 통신해야 합니다.
리소스 제한: Docker 컨테이너의 CPU/메모리 제한을 꼭 걸어두세요. 에이전트가 무한 루프에 빠져서 자원을 다 먹어치우는 건 흔한 사고입니다.
임시 환경: 가능한 한 상태를 저장하지 않는(Stateless) 작업 위주로 돌리고, 컨테이너는 작업을 마치면 폐기하는 방식이 안전합니다.