Paperclip을 로컬에서만 쓰다가, 팀원이나 외부 네트워크에서도 접속할 수 있게 만들고 싶다면 인증 모드(authenticated mode)로 전환해야 합니다. 기본 설치는 local_trusted 모드로 127.0.0.1에만 바인딩되어 외부 접속이 차단됩니다. 이 가이드에서는 인증 모드 설정, CEO 초대 링크 생성, 허용 호스트네임 관리, 그리고 Tailscale을 활용한 프라이빗 네트워크 접속까지 단계별로 안내합니다. 배포 모드 이해하기 Paperclip은 세 가지 배포 모드를 지원합니다. 외부 접속을 위해서는 반드시 authenticated 모드가 필요합니다. 모드바인딩인증용도 local_trusted (기본)127.0.0.1불필요로컬 개발, 혼자 사용 authenticated/private0.0.0.0JWT 기반팀/외부 접속, 프라이빗 네트워크 authenticated/public0.0.0.0JWT 기반인터넷 공개 배포 핵심 제약: local_trusted 모드에서는 0.0.0.0 바인딩이 불가능합니다. 외부 접속을 위해서는 반드시 authenticated 모드로 전환해야 합니다. 방법 1: 새로 설치하면서 인증 모드 선택 아직 Paperclip을 설치하지 않았거나 초기화할 수 있다면 가장 깔끔한 방법입니다. # 기존 설정 초기화 (필요 시) rm -rf ~/.paperclip # 온보딩 실행 npx paperclipai onboard 대화형 마법사에서 다음을 선택합니다: Advanced setup 선택 Deployment mode: Authenticated 선택 Exposure profile: Private network 선택 Bind address: 0.0.0.0 입력 온보딩이 완료되면 서버가 0.0.0.0:3100에서 시작되며, 같은 네트워크의 다른 기기에서 접속할 수 있습니다. 방법 2: 기존 설치를 인증 모드로 전환 이미 local_trusted로 설치했다면, 설정 파일을 수정하여 전환합니다. Step 1: config.json 수정 # 설정 파일 위치 확인 ls ~/.paperclip/instances/default/config.json # 편집 nano ~/.paperclip/instances/default/config.json 다음 값을 변경합니다: { "deployment": { "mode": "authenticated", "exposure": "private" }, "server": { "host": "0.0.0.0", "port": 3100 } } Step 2: CEO 초대 링크 생성 인증 모드에서는 첫 번째 관리자(CEO)를 초대해야 합니다: paperclipai auth bootstrap-ceo 이 명령은 일회용 초대 링크를 생성합니다. 기본 72시간 유효하며, 최대 720시간(30일)까지 설정 가능합니다. 옵션기본값설명 --force-기존 관리자가 있어도 새 초대 링크 생성 --expires-hours72초대 링크 유효 시간 (최대 720) --base-url-외부 접속용 공개 URL 지정 Step 3: 외부 접속 URL로 초대 링크 생성 외부에서 접속할 URL이 있다면 --base-url을 지정합니다: # Tailscale 사용 시 paperclipai auth bootstrap-ceo --base-url https://my-server.tail1234.ts.net:3100 # 고정 IP 사용 시 paperclipai auth bootstrap-ceo --base-url http://192.168.1.100:3100 # 도메인 사용 시 paperclipai auth bootstrap-ceo --base-url https://paperclip.example.com 생성된 링크를 브라우저에서 열면 CEO 계정 등록 화면이 나타납니다. 방법 3: Tailscale로 프라이빗 네트워크 접속 가장 안전하면서 간편한 외부 접속 방법입니다. Tailscale은 VPN 없이 기기 간 프라이빗 네트워크를 구성합니다. Step 1: Tailscale 인증 모드로 실행 # 소스에서 빌드한 경우 pnpm dev --tailscale-auth # 또는 npx로 설치한 경우 paperclipai run --tailscale-auth 이 플래그가 자동으로 인증 모드 활성화 + 0.0.0.0 바인딩을 처리합니다. Step 2: Tailscale 호스트네임 허용 # 접속할 기기의 Tailscale 호스트네임 추가 paperclipai allowed-hostname my-macbook-pro paperclipai allowed-hostname team-member-laptop Step 3: CEO 초대 paperclipai auth bootstrap-ceo --base-url https://my-server.tail1234.ts.net:3100 이후 Tailscale 네트워크에 연결된 모든 허용 기기에서 대시보드에 접속할 수 있습니다. 허용 호스트네임 관리 인증 모드에서는 허용 호스트네임 목록(allowlist)으로 접속을 제한합니다: # 호스트네임 추가 paperclipai allowed-hostname my-macbook-pro paperclipai allowed-hostname office-desktop paperclipai allowed-hostname team-server # Tailscale 머신 이름도 사용 가능 paperclipai allowed-hostname john-mbp.tail1234.ts.net 보안 파일 구조 인증 모드에서 Paperclip이 관리하는 보안 파일들입니다: ~/.paperclip/instances/default/ config.json # 메인 설정 (배포 모드, 바인딩 주소) .env.local # JWT 시크릿 (세션 토큰 서명용) secrets/ master.key # 민감 데이터 암호화 키 context.json # CLI 컨텍스트 프로파일 주의: .env.local과 master.key는 절대 외부에 노출하지 마세요. 이 파일이 유출되면 모든 세션 토큰과 암호화된 데이터가 위험해집니다. 환경변수로 설정하기 설정 파일 대신 환경변수로도 배포 모드를 제어할 수 있습니다. Docker나 클라우드 배포 시 유용합니다: # 배포 모드 설정 export PAPERCLIP_DEPLOYMENT_MODE="authenticated" export PAPERCLIP_DEPLOYMENT_EXPOSURE="private" # 바인딩 설정 export HOST="0.0.0.0" export PORT="3100" # AI 에이전트 API 키 export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." # 서버 실행 paperclipai run 트러블슈팅 증상원인해결 0.0.0.0 바인딩 실패local_trusted 모드authenticated 모드로 전환 (위 Step 참고) 외부에서 접속 안 됨방화벽/포트 차단3100 포트 개방: sudo ufw allow 3100 초대 링크 만료기본 72시간 초과--force --expires-hours 720으로 재생성 호스트네임 거부allowlist 미등록paperclipai allowed-hostname [이름] JWT 인증 오류.env.local 손상삭제 후 paperclipai configure로 재생성 핵심 정리 외부 접속을 위해서는 authenticated 모드 + 0.0.0.0 바인딩이 필수 새 설치: 온보딩에서 Advanced setup → Authenticated → Private network → 0.0.0.0 선택 기존 설치: config.json에서 mode와 host 수정 paperclipai auth bootstrap-ceo --base-url [URL]로 첫 관리자 초대 paperclipai allowed-hostname [이름]으로 접속 허용 기기 관리 Tailscale: --tailscale-auth 플래그로 가장 간편하게 프라이빗 접속 구성 보안 파일(.env.local, master.key)은 절대 외부 노출 금지 참조 링크 Paperclip CLI Overview - auth bootstrap-ceo CLI 인증 명령어 공식 문서 Paperclip Local Deployment Guide 로컬 배포 모드, Tailscale 연동, 바인딩 설정 Issue #65: Unable to bind 0.0.0.0 during onboarding 0.0.0.0 바인딩 문제 해결 방법 (커뮤니티 솔루션) paperclipai/paperclip - GitHub 공식 저장소 (소스 코드, 이슈 트래커)