소개
Agent Bridge 는 맥에서 도는 Claude Code 세션을 직접 올린 웹 서버에 이어 주는 셀프호스팅 시스템이에요. 폰이나 다른 컴퓨터의 브라우저에서 세션을 보고 조작할 수 있고, 세션을 다른 맥으로 옮길 수도 있어요.
세션은 언제나 맥에서 돌아요. 서버는 Claude 를 실행하지 않고, 맥과 브라우저 사이에서 화면과 명령을 중계해요.
이 페이지는 전체 그림과 쓰는 이유를 다뤄요. 설치와 첫 세션은 시작하기를 보세요.
어떻게 동작하나요?
Agent Bridge 에는 네 가지 구성 요소가 있어요.
| 구성 요소 | 어디서 도나요 | 하는 일 |
|---|---|---|
| 서버 | 직접 올린 컨테이너 | 로그인, 맥 등록, 중계, 옮기기, 알림 |
| 에이전트 | 맥(127.0.0.1) | Claude Code 를 띄우고, 읽고, 조작해요 |
| 연동 페이지 | 맥의 Chrome 탭 | 에이전트와 서버 사이의 메시지를 옮겨요 |
| 조작 페이지 | 폰·PC 브라우저 | 사람이 세션을 보고 다루는 화면이에요 |
이 문서는 에이전트가 설치된 맥을 호스트라고 불러요. Claude Code 실행 하나는 세션이라고 불러요.
구성과 연결
에이전트는 맥 안의 127.0.0.1 에서만 들어요. 서버에 직접 연결하지도 않아요. 그 대신 맥의 Chrome 에 열어 둔 사이트 탭이 에이전트와 서버를 양쪽으로 이어요. 그래서 맥에 포트를 열거나 터널을 둘 필요가 없어요. 자세한 내용은 구성과 연결을 보세요.
세션의 일생
세션은 뜨는 중, 대기, 작업 중, 응답 대기 같은 상태를 오가요. 에이전트는 Claude Code 훅과 터미널 화면을 함께 읽어 상태를 알아내요. 터미널에 뜬 확인 창은 조작 페이지에 카드로 올라오고, 카드에 답하면 터미널에 그대로 전해져요. 자세한 내용은 세션의 일생을 보세요.
옮기기와 작업 폴더 싱크
대화의 원본은 맥에 있어요. 서버는 대화를 디스크에 저장하지 않고, 옮기는 동안에만 메모리에 사본을 둬요. 옮기기는 보내는 맥에서 마지막 싱크를 하고, 받는 맥에서 같은 대화를 이어 연 뒤에 보내는 맥을 내려놓는 순서로 진행돼요. 그래서 보내는 맥이 연결돼 있어야 옮길 수 있어요. 작업 폴더는 통째로 옮기지 않고, 지침 파일과 git 브랜치·커밋만 맞춰요. 자세한 내용은 옮기기와 작업 폴더 싱크를 보세요.
보안 모델
서버는 연결된 맥의 세션을 조작할 수 있으므로 믿을 수 있는 서버여야 해요. 에이전트는 사이트의 출처와 맥마다 만든 키를 확인해요. 자동 업데이트는 운영자의 서명이 맞을 때만 받아요. 세션마다 비밀번호 잠금을 걸어 목록과 알림에서 내용을 가릴 수 있어요. 자세한 내용은 보안 모델을 보세요.
왜 Agent Bridge 인가요?
Claude Code 는 맥의 터미널에서 돌아요. 자리를 떠나면 권한 요청 하나에 작업이 멈추고, 다른 맥에서 이어 가려면 대화를 다시 설명해야 해요. Agent Bridge 는 이 문제를 다음처럼 풀어요.
- 맥에 포트를 열지 않아요. 바깥으로 나가는 연결은 맥의 브라우저 탭이 만들어요. 공유기 설정, 터널, VPN, 고정 IP 가 필요 없어요.
- 세션은 맥에 남아요. 코드, 파일, 자격 증명은 맥에 있어요. 서버는 Claude 를 실행하지 않고, 대화도 저장하지 않아요.
- 맥 사이를 옮겨 다녀요. 두 맥이 연결돼 있으면, 맥북에서 하던 세션을 아이맥으로 옮겨 같은 대화를 이어 가요. 같은 대화가 두 맥에서 동시에 돌지 않고, 옮기기가 실패하면 세션은 보낸 맥에 그대로 남아요.
- 폰에 맞춘 화면이에요. 조작 페이지는 폰 폭(390 px)을 기준으로 만들었어요. 권한 요청, 질문, 플랜 승인을 카드로 받고, 답이 오면 웹 푸시로 알려 줘요.
- 내 서버에 올려요. 서버는 Go 바이너리 하나와 데이터 폴더로 돌아요. 소스는 GNU AGPL v3 로 공개돼 있어요.
Agent Bridge 는 사용자마다 호스트와 세션을 나눠요. 여러 사람이 한 세션을 함께 쓰는 기능은 없어요. 호스트는 macOS 만 지원해요.