원격 서버 연결

모든 클라이언트는 데이터를 소유하는 cc_server 위의 렌더러입니다. 데스크톱은 자신 안에서 서버를 실행할 수 있지만, app.usectrl.dev의 웹 앱은 그럴 수 없습니다. 브라우저 탭은 서버를 호스팅할 수 없기 때문입니다. 어느 쪽이든 이 가이드는 클라이언트를 다른 곳에서 실행 중인 서버, 즉 작은 장비나 클라우드 VM, 빌드 서버로 지정합니다.

사전 요구 사항

실행 중인 cc_server. 아직 없다면 헤드리스 서버 실행을 참고하십시오.
서버가 발급한 세 가지 페어링 값 — 서버 URL(ws://…/rpc 또는 wss://…/rpc), 기기 ID, 페어링 키 — 또는 워크스페이스 관리자가 발급한 일회용 초대 코드. 초대를 사용하면 사용자가 프로비저닝되고 멤버십이 기록되며 이 클라이언트의 자격 증명이 대신 발급되므로, 기기 ID나 키를 직접 다룰 필요가 없습니다.

서버에 닿을 수 있는지 확인

로컬 서버는 아무것도 필요하지 않습니다. 브라우저가 루프백을 신뢰할 수 있는 오리진으로 취급하므로 ws://localhost:9030/rpc는 데스크톱과 브라우저 모두에서 작동합니다.

다른 머신의 서버는 다릅니다. app.usectrl.dev는 HTTPS로 제공되므로 브라우저는 이미 신뢰하는 인증서가 있는 wss:// 소켓만 엽니다. 게다가 cc_server는 TLS 없이 비루프백 주소에 바인딩하는 것을 애초에 거부합니다. 다음 중 하나를 제공하십시오.

--tls-cert와 --tls-key로 인증서를 직접 지정
앞단에 TLS 종료 리버스 프록시를 두고 서버를 --insecure로 시작(프록시 뒤는 평문이며, 신뢰할 수 있는 네트워크에서만)
인증서를 공급하는 터널이나 VPN — Tailscale, cloudflared 등. 설정 → 서버 → 연결 및 상태의 이 서버 공유 아래에 내장 터널 옵트인이 있습니다.

서버 쪽에서 놓치기 쉬운 설정이 두 가지 있습니다. 프록시, NAT 또는 터널 뒤에서는 클라이언트가 실제로 접속할 주소로 --public-url을 설정하십시오. 기본값은 로컬 바인드이므로 이를 설정하지 않으면 클라이언트가 잘못된 호스트를 시도합니다. 또한 웹 빌드를 직접 호스팅하는 경우 그 오리진을 --allowed-origins에 추가하십시오. 이 목록의 기본값은 https://app.usectrl.dev 하나뿐이며, 루프백과 네이티브 클라이언트는 항상 허용됩니다.

데스크톱 앱 연결

새로 설치한 경우:

Control Center를 실행합니다. 첫 실행 화면에서 **Control Center를 어떻게 실행할까요?**라고 묻습니다.
이 앱에서 실행 대신 연결 필드에 서버 URL과, 초대 코드 또는 기기 ID와 페어링 키를 입력합니다.
연결을 클릭합니다. Control Center가 서버에 접속해 워크스페이스 받은편지함으로 이동합니다.

이미 자체 서버를 실행 중인 데스크톱의 경우:

설정 → 서버 → 연결 및 상태를 엽니다.
서버 추가를 클릭합니다. 서버 URL(wss://host:9030/rpc)과, 초대 코드 또는 기기 ID와 페어링 키를 입력합니다. URL 필드의 접미사 버튼은 LAN이나 Tailnet에서 cc_server 인스턴스를 검색합니다.
연결을 클릭한 다음 새 서버 행에서 전환을 클릭합니다.

전환은 실시간으로 이루어집니다. 앱이 재시작 없이 새 세션을 중심으로 즉석에서 다시 구성됩니다. 연결에 실패하면 현재 서버에 그대로 남아 오류를 확인합니다. 현재 접속한 서버의 행에는 전환 동작이 없습니다. 로컬 서버는 첫 번째 행이며 이 앱에서 실행으로 표시됩니다.

전환하고 나면 데스크톱은 데이터베이스를 소유하지 않습니다. 모든 화면이 WebSocket을 통해 원격 서버로 읽고 씁니다.

웹 클라이언트 연결

웹 빌드는 항상 원격입니다.

app.usectrl.dev 또는 직접 호스팅한 웹 빌드를 엽니다.
서버 URL과, 초대 코드 또는 기기 ID와 페어링 키를 입력합니다.
클라이언트가 서버에 접속해 데스크톱과 동일한 인터페이스를 렌더링합니다.

URL에 페어링 딥 링크가 있으면 필드가 미리 채워집니다. 페어링 키는 URL 프래그먼트에 실리며, 브라우저는 이 부분을 페이지를 호스팅하는 서버로 보내지 않으므로 정적 호스트는 키를 볼 수 없습니다.

브라우저가 하지 않는 것

웹 클라이언트는 데스크톱과 동일한 서버를 읽고 쓰지만, 몇몇 표면은 네이티브 창이나 머신 자체의 장치가 필요합니다.

OS 알림 토스트, 알림 소리, 주변 배너 레일 없음(앱 내 알림 센터는 여전히 작동)
서버 추가 대화 상자에서 LAN 또는 Tailnet 서버 검색 없음
앱 내 기사 리더 없음 — 뉴스피드 기사는 새 탭에서 열림
회의 요약 재실행 불가, 처리 중인 요약 취소 불가

두 가지는 빠진 것이 아니라 다르게 동작합니다. 회의 녹음은 브라우저에서 작동하며, 마이크와 오디오 트랙을 포함한 화면 공유를 캡처합니다. IDE에서 열기도 작동하지만, 서버에 서버의 디스플레이에서 편집기를 실행하도록 요청하므로, 편집기가 설치되지 않은 헤드리스 호스트에서는 버튼이 스스로 숨겨집니다.

문제 해결

연결 시간 초과: 서버는 클라이언트에서 닿을 수 있어야 합니다. 바인드(--bind any)와 포트가 열려 있는지, --public-url이 클라이언트가 실제로 접속할 수 있는 주소를 가리키는지 확인하십시오. 공용 인터넷에서는 TLS가 필수입니다. 프록시 뒤에서 --insecure로 시작하지 않은 한 평문 비루프백 바인드는 시작 시 거부됩니다.
브라우저는 연결을 거부하지만 네이티브 클라이언트는 작동: 브라우저의 오리진이 서버의 --allowed-origins 목록에 없습니다. 기본값은 https://app.usectrl.dev(및 루프백)만 허용합니다.
페어링 키 거부: 서버에서 cc_server pair를 다시 실행해 해당 기기의 키를 교체한 다음 새 키를 입력하십시오. 폐기된 기기는 자격 증명이 사라진 것을 확인하고 안전하게 실패합니다. 폐기는 실행 중인 세션을 몇 초 안에 끊습니다.
잘못된 워크스페이스: 워크스페이스는 URL(/workspaces/:workspaceId/…)의 일부이며 모든 호출에 함께 전달되므로, 한 클라이언트에서 워크스페이스를 전환해도 자신의 뷰만 바뀝니다. 자신이 멤버인 워크스페이스에만 접근할 수 있으며, 그 외에는 “Not a member of this workspace”로 거부됩니다. 워크스페이스와 격리를 참고하십시오.