브릿지 & 원격 제어

브릿지 시스템은 로컬 CLI 세션을 클라우드 기반 인터페이스(예: claude.ai)와 양방향으로 연결합니다. 단순한 출력 스트리밍이 아니라 권한, 도구 호출, 파일 편집까지 원격에서 제어할 수 있는 완전한 양방향 파이프라인입니다.

핵심 구성 요소:

• 아키텍처: 아웃바운드(CLI → 클라우드)와 인바운드(클라우드 → CLI) 데이터 흐름의 비대칭 설계
• 전송 레이어: HybridTransport와 SSETransport를 통한 메시지 전달
• FlushGate: 클라이언트가 이전 메시지를 소비할 때까지 다음 전송을 대기하는 배압 메커니즘
• 원격 제어: 5개의 자격 게이트를 통과해야 활성화되는 보안 커맨드 채널

브릿지는 두 방향의 데이터 흐름을 서로 다른 전송 메커니즘으로 처리합니다.

아웃바운드 흐름 (CLI → 클라우드)

CLI의 모든 상태 변경(도구 실행 결과, 어시스턴트 응답 스트리밍, 권한 요청 등)은 SSE(Server-Sent Events) 스트림을 통해 클라우드로 전송됩니다. 이 방향은 연속적이고 실시간입니다.

인바운드 흐름 (클라우드 → CLI)

사용자 입력, 권한 승인/거부, 중단 요청 등은 HTTP POST 요청으로 CLI에 전달됩니다. 각 요청은 독립적이며 멱등성을 가집니다.

// bridge/server.ts — 인바운드 메시지 디스패치
switch (message.type) {
  case 'user_input':
    handleUserInput(message.text)
    break
  case 'permission_response':
    resolvePermission(message.requestId, message.granted)
    break
  case 'abort':
    abortCurrentTurn()
    break
}

브릿지 시스템은 두 번의 주요 반복을 거쳤습니다. v1은 단방향 스트리밍에 초점을 맞췄고, v2는 완전한 양방향 제어를 실현했습니다.

전송 레이어는 브릿지의 물리적 통신을 추상화합니다.

SSETransport

아웃바운드 전용 전송으로, 클라이언트가 /events 엔드포인트에 GET 요청을 보내면 서버는 SSE 스트림을 열어 상태 변경을 실시간으로 푸시합니다.

// bridge/transport.ts — SSE 이벤트 전송
class SSETransport {
  send(event: BridgeEvent): void {
    const data = JSON.stringify(event)
    this.response.write(`data: ${data}\n\n`)
  }

  keepAlive(): void {
    this.response.write(`: keepalive\n\n`)  // SSE 주석으로 연결 유지
  }
}

HybridTransport

v2에서 도입된 복합 전송입니다. SSETransport를 래핑하면서 인바운드 HTTP POST 핸들러를 추가합니다. 양방향 통신의 핵심 추상화 레이어입니다.

// bridge/transport.ts — HybridTransport 구조
class HybridTransport {
  private sse: SSETransport
  private flushGate: FlushGate

  async send(event: BridgeEvent): Promise<void> {
    await this.flushGate.waitForFlush()  // 배압 대기
    this.sse.send(event)
  }

  handleInbound(req: IncomingMessage): void {
    const message = parseBody(req)
    this.dispatch(message)
  }
}

FlushGate는 클라이언트가 이전 메시지를 소비했음을 확인할 때까지 다음 메시지 전송을 차단하는 배압(backpressure) 메커니즘입니다. 빠른 도구 실행이 느린 네트워크 연결을 압도하는 것을 방지합니다.

// bridge/flushGate.ts — 배압 제어
class FlushGate {
  private pending: Promise<void> | null = null
  private resolve: (() => void) | null = null

  async waitForFlush(): Promise<void> {
    if (this.pending) {
      await this.pending  // 이전 flush 완료 대기
    }
    this.pending = new Promise(r => this.resolve = r)
  }

  ack(): void {
    this.resolve?.()     // 클라이언트가 ACK를 보내면 게이트 해제
    this.pending = null
  }
}

원격 인터페이스에서 도구 실행 권한을 승인/거부할 수 있어야 합니다. 권한 브릿지는 로컬 권한 시스템과 원격 클라이언트 사이의 프록시 역할을 합니다.

// bridge/permissions.ts — 원격 권한 요청 흐름
async function requestPermissionRemotely(
  tool: ToolName,
  args: ToolArgs,
): Promise<PermissionResult> {
  const requestId = randomUUID()
  // 1. 클라우드에 권한 요청 이벤트 전송
  bridge.send({ type: 'permission_request', requestId, tool, args })
  // 2. 사용자 응답 대기 (승인 또는 거부)
  return await waitForPermissionResponse(requestId)
}

권한 요청은 도구 이름, 인수, 요청 ID를 포함합니다. 클라우드 UI는 이를 표시하고 사용자의 승인/거부를 permission_response 메시지로 반환합니다. 타임아웃 시 자동 거부됩니다.

원격 제어 모드는 보안에 민감하므로 5개의 자격 게이트를 모두 통과해야 활성화됩니다.

1. 인증 게이트: 유효한 OAuth 토큰이 있고, 토큰이 원격 제어 범위를 포함해야 함
2. 구독 게이트: 사용자의 구독 플랜이 원격 제어를 지원해야 함 (Max/Team/Enterprise)
3. 기능 플래그 게이트: GrowthBook 원격 제어 기능 플래그가 활성화되어야 함
4. 세션 게이트: 세션이 --remote-control 플래그로 시작되어야 함
5. 네트워크 게이트: 브릿지 서버가 성공적으로 바인딩되고 클라우드와 핸드셰이크를 완료해야 함

// remote-control/gates.ts — 5개 게이트 검증
async function validateRemoteControlEligibility(): Promise<GateResult> {
  const gates = [
    checkAuthGate(),        // OAuth 토큰 + 범위
    checkSubscriptionGate(), // 플랜 레벨
    checkFeatureFlagGate(),  // GrowthBook
    checkSessionGate(),      // --remote-control 플래그
    checkNetworkGate(),      // 브릿지 핸드셰이크
  ]
  const results = await Promise.all(gates)
  return results.every(r => r.passed)
    ? { eligible: true }
    : { eligible: false, reason: results.find(r => !r.passed)!.reason }
}

CCR(Claude Code Remote) 환경에서 브릿지는 컨테이너 내부에서 실행되며, 업스트림 프록시를 통해 외부와 통신합니다.

CCR 통합

CCR 컨테이너 내부에서 브릿지 서버는 자동으로 시작됩니다. 업스트림 프록시가 WebSocket 연결을 중계하며, 브릿지는 프록시의 로컬 포트에 바인딩합니다. 환경 변수 CLAUDE_CODE_BRIDGE_PORT가 포트를 지정합니다.

독립 브릿지 서버

로컬 개발 환경에서도 claude bridge-server 명령으로 독립적인 브릿지 서버를 실행할 수 있습니다. 이를 통해 커스텀 클라이언트(IDE 확장, 웹 UI 등)가 CLI 세션에 연결할 수 있습니다.

// 독립 브릿지 서버 시작
$ claude bridge-server --port 3456

// 클라이언트 연결
// SSE: GET http://localhost:3456/events
// 입력: POST http://localhost:3456/message
// ACK:  POST http://localhost:3456/ack