시작하기
이 가이드를 마치면 맥 한 대를 서버에 연결하고, 폰에서 새 세션을 띄워 첫 답을 받을 수 있어요. 순서는 로그인 → 맥에 에이전트 설치 → 맥의 Chrome 에 탭 열어 두기 → 폰에서 세션 시작이에요.
내부 구조는 다루지 않아요. 구조가 궁금하면 구성과 연결을 보세요.
시작하기 전에
- 돌고 있는 Agent Bridge 서버. 아래에서
SITE는 서버 주소예요(예:https://bridge.example.com). 서버가 없으면 서버 올리기부터 하세요. - GitHub 계정. 서버 운영자가 허용한 계정만 들어갈 수 있어요.
- macOS 맥 한 대. Node.js 18 이상, git, Claude Code(
claude)가 필요하고,claude는 로그인돼 있어야 해요. - 맥의 Google Chrome. 맥과 서버를 잇는 탭은 Chrome 에서 열어요.
- 폰 브라우저. iOS·iPadOS Safari 16.4 이상, Android Chrome 111 이상이에요.
버전 전체는 지원 환경을 보세요.
서버 안의 시작 가이드
로그인한 뒤 SITE/guide 를 열면 같은 단계를 화면에서 따라갈 수 있어요. 맥이 연결되거나 세션이 생기면 그 단계가 저절로 체크돼요.
1. GitHub 로 로그인하세요
- 맥의 Chrome 에서
SITE를 여세요. - GitHub 로그인 버튼을 누르고 GitHub 에서 허락하세요.
- 세션 목록이 있는 조작 페이지가 열리면 다음 단계로 가세요.
"승인을 기다리는 중이에요" 페이지가 보이면, 그 계정은 아직 허용되지 않은 것이에요. 사용 요청은 서버 운영자에게 전달돼요. 승인되어도 알림은 가지 않으니, 운영자에게 승인을 받은 뒤 다시 GitHub 로 로그인하세요. 운영자 쪽 절차는 접근 관리와 운영 화면을 보세요.
2. 맥에 에이전트를 설치하세요
맥의 터미널에서 다음 명령을 한 번 실행하세요.
curl -fsSL SITE/install.sh | bash설치 스크립트는 이 순서로 일해요.
- macOS 인지 확인해요. 다른 운영체제면 멈춰요.
- 필요한 도구를 확인해요:
node,tmux,git,claude. 없는 도구는 Homebrew 가 있으면 설치할지 물어요.claude는 직접 설치하도록 안내해요. node가 없거나 18 보다 낮으면 멈춰요.- 에이전트 파일을 받아
~/.claude-bridge/에 둬요. - 처음이면 이 맥의 종류(아이맥, 맥북 등)와 사이트에 보일 이름을 물어요. 그냥 Enter 를 누르면 감지한 값을 써요.
- 에이전트를 launchd 백그라운드 서비스로 설치해요. 맥에 로그인하면 에이전트가 저절로 켜져요.
- 브라우저로 연동 페이지(
SITE/bridge)를 열어요.
백그라운드 서비스로 설치했습니다. 이 터미널은 닫아도 됩니다. 가 보이면 설치가 끝난 것이에요.
tmux 는 없어도 돼요. 세션은 에이전트가 직접 받아 두는 zeropty 에서 돌고, tmux 는 그게 안 될 때의 대비예요.
아직 없는 도구
끝에 아직 없는 도구: 가 찍혀도 에이전트는 켜져요. 그 도구를 설치하기 전에는 세션을 시작할 수 없어요. 설치한 뒤에는 에이전트를 다시 켜지 않아도 바로 돼요.
설치 옵션
bash -s -- 뒤에 옵션을 붙이면 묻지 않고 정할 수 있어요.
curl -fsSL SITE/install.sh | bash -s -- --kind macbook --name "작업 맥북"| 옵션 | 뜻 |
|---|---|
--kind <종류> | 맥 종류. imac, macbook, macmini, macstudio, other 중 하나예요 |
--name <이름> | 사이트에 보일 이 맥의 이름이에요 |
--no-open | 끝난 뒤 브라우저를 열지 않아요 |
--foreground | 백그라운드 서비스 대신 이 터미널에서 에이전트를 돌려요 |
옵션 전체는 설치 스크립트와 에이전트 명령을 보세요.
3. 맥의 Chrome 에 사이트 탭을 열어 두세요
에이전트는 혼자서는 서버에 연결하지 않아요. 맥의 브라우저에 열린 사이트 탭이 에이전트와 서버를 이어요.
설치 스크립트가 연 연동 페이지가 Chrome 인지 확인하세요. 기본 브라우저가 Safari 면 Safari 로 열려요. 그때는 다음 명령으로 연동 링크를 다시 받아 Chrome 주소창에 붙여 넣으세요.
shnode ~/.claude-bridge/agent.mjs linkChrome 이 "로컬 네트워크의 기기에 연결" 을 허용할지 물으면 허용을 누르세요. 이 맥의 에이전트(
127.0.0.1)에 붙는 데 필요해요.로그인돼 있지 않으면 GitHub 로그인으로 갔다가 연동 페이지로 돌아와요.
연동 페이지에 이 맥의 이름과 로그인한 계정이 보이면 연결된 것이에요.
이 탭을 닫지 마세요. 같은 Chrome 에 조작 페이지(SITE) 탭이 열려 있어도 그 탭이 대신 이어요. 사이트 탭을 모두 닫으면 그 맥은 끊겨요. 탭 없이 늘 연결해 두려면 맥을 늘 연결해 두기를 보세요.
4. 폰에서 사이트를 여세요
둘 중 하나를 고르세요.
- 폰에서 직접 로그인: 폰 브라우저에서
SITE를 열고 GitHub 로 로그인하세요. - QR 로 로그인: 맥의 조작 페이지에서 기기 화면(
SITE/hosts)을 열고 QR 만들기를 누르세요. 폰 카메라로 QR 을 찍으면 폰이 같은 계정으로 로그인돼요. QR 은 5분 동안만 쓸 수 있고, 만료되면 새 QR 을 누르세요.
폰 브라우저의 "홈 화면에 추가" 로 앱처럼 쓸 수 있어요. iPhone 에서 웹 푸시를 받으려면 홈 화면에 추가해야 해요.
5. 새 세션을 시작하세요
- 조작 페이지에서 +(새 세션)를 누르세요.
- 기기에서 방금 연결한 맥을 고르세요.
- 폴더는 그대로 두세요. 기본값은
~/bridge/works/<그룹>/<월일>-<id>모양의 새 폴더이고, 에이전트가 만들어요. 이미 있는 프로젝트에서 시작하려면 폴더 칸을 눌러 고르세요. - 첫 메시지에 할 일을 적으세요. 예:
이 폴더에 README.md 를 만들고 오늘 날짜를 적어 줘. - 시작을 누르세요.
세션 화면이 열리고 상태가 뜨는 중으로 보여요.
6. 메시지를 주고받으세요
- Claude 가 답을 쓰는 동안 상태는 작업 중이고, 지금 쓰는 중인 글이 미리 보여요.
- 파일을 쓰려는 등 권한이 필요하면 화면에 카드가 떠요. 고른 답은 맥의 터미널에 그대로 전해져요.
- 답이 끝나면 상태가 대기로 바뀌어요. 입력칸에 다음 메시지를 적고 보내기 버튼을 누르세요. 폰에서는 Enter 가 줄바꿈이에요.
작업 중에 보낸 메시지는 바로 들어가지 않고 붙잡은 글로 기다렸다가, 도구나 턴이 끝나면 전해져요.
확인하기
다음이 모두 보이면 성공이에요.
- 폰의 세션 목록에 새 세션이 있고, 상태가 대기예요.
- 세션 화면에 첫 메시지와 Claude 의 답이 있어요.
- 기기 화면(
SITE/hosts)에서 이 맥이 연결됨으로 보여요. - 맥에서
node ~/.claude-bridge/agent.mjs service status를 실행하면서비스: 설치됨, 켜져 있음과에이전트: 127.0.0.1:<포트> 에서 응답함이 찍혀요.
문제가 생기면
| 증상 | 해결 |
|---|---|
| 연동 페이지에 "Safari 는 이 페이지가 맥의 에이전트(127.0.0.1)에 붙는 것을 막을 수 있습니다" | 3단계처럼 link 명령으로 받은 주소를 Chrome 에서 여세요 |
| "브라우저가 이 사이트의 로컬 네트워크 접근을 막고 있습니다" | 주소창 왼쪽의 사이트 설정에서 "로컬 네트워크 접근" 을 허용으로 바꾸고 새로고침하세요 |
| "이 사이트의 다른 탭이 연동 중" | 정상이에요. 같은 Chrome 의 다른 탭이 잇고 있어요. 그 탭이 닫히면 이 탭이 이어받아요 |
| 새 세션 화면에 "연결된 맥이 없어요" | 맥의 Chrome 에 사이트 탭이 열려 있는지 확인하세요 |
| 세션이 시작되지 않고 도구가 없다는 오류 | 맥에서 node ~/.claude-bridge/agent.mjs doctor 로 무엇이 없는지 확인하세요 |
더 많은 경우는 문제 해결을 보세요.
다음 단계
- 폰에서 세션 다루기: 카드, 붙잡은 글, 중단 같은 일상 조작을 익혀요.
- 세션 옮기기: 다른 맥으로 세션을 넘겨요.
- 알림과 웹 푸시: 권한 요청과 답을 폰으로 받아요.
- 세션의 일생: 상태와 카드가 어떻게 정해지는지 알아봐요.