cc_server CLI

모든 프로세스 플래그는 CLI 플래그나 환경 변수로 지정할 수 있습니다. 우선순위는 플래그, 그다음 환경 변수, 마지막으로 기본값입니다. 서드파티 자격 증명은 예외입니다 — 아래를 참고하십시오.

알 수 없는 플래그는 조용히 무시됩니다

인수 파서는 직접 작성한 것이라 인식하지 못하는 것은 무엇이든 건너뜁니다. 따라서 오타(--tls-key-file, --bindany)가 나도 오류가 발생하지 않고, 서버는 그냥 기본값으로 시작합니다. 플래그가 아무 효과가 없는 것 같으면 시작 로그 줄을 확인하십시오.

핵심

플래그	환경 변수	기본값	의미
--data-dir	CC_SERVER_DATA_DIR	OS의 사용자별 애플리케이션 데이터 디렉터리(아래 참고)	데이터베이스, 시크릿, 모델, 캐시된 미디어
--port	CC_SERVER_PORT	9030	TCP 포트(0 = 임시 포트)
--bind	CC_SERVER_BIND	loopback	loopback, 또는 모든 인터페이스를 대상으로 하는 any/all/0.0.0.0(TLS 또는 --insecure 필요)
--repo-roots	CC_SERVER_REPO_ROOTS	서버 사용자의 홈 디렉터리	클라이언트가 저장소를 등록할 때 탐색할 수 있는 콤마로 구분된 기준 디렉터리입니다. 루트 위쪽으로의 탐색은 거부됩니다
--log-level	CC_SERVER_LOG_LEVEL	warning	debug, info, warning, error 중 하나입니다. 부팅/준비 완료 로그 줄은 항상 출력됩니다
--server-name	CC_SERVER_NAME	머신의 호스트 이름	피커, 디스커버리, 페어링 화면에 표시되는 이름

도달 가능성과 TLS

플래그	환경 변수	기본값	의미
--tls-cert	CC_SERVER_TLS_CERT	미설정	PEM 인증서 체인입니다. 키와 함께 설정하면 프로세스 내에서 wss://를 제공합니다
--tls-key	CC_SERVER_TLS_KEY	미설정	인증서와 짝을 이루는 PEM 개인 키
--insecure	CC_SERVER_INSECURE	off	비루프백 주소에 평문 바인딩을 허용합니다. TLS를 종료하는 프록시 뒤의 신뢰할 수 있는 네트워크에서만 사용하십시오. TLS가 구성되어 있으면 무시됩니다
--public-url	CC_SERVER_PUBLIC_URL	바인딩에서 파생됨	이 서버가 페어링된 클라이언트에 알리는 RPC URL입니다. 프록시, NAT, 터널 뒤에서는 이를 명시적으로 설정하십시오 — 기본값은 로컬 바인드를 추측한 것에 불과합니다
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	교차 출처로 /rpc를 호출할 수 있는 브라우저 오리진을 콤마로 구분한 목록입니다. 루프백과 네이티브 클라이언트는 항상 허용됩니다
--web-client-url	CC_SERVER_WEB_CLIENT_URL	미설정	싱글 사인온 콜백이 되돌아오는, 호스팅된 웹 클라이언트의 오리진입니다
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	휴대폰이 직접 경로 없이 서버에 도달할 수 있도록 이 서버가 참여하는 릴레이 브로커입니다
--mdns	CC_SERVER_MDNS	auto	LAN 광고 방식으로 auto(루프백 너머로 바인딩된 경우에만), on, off 중 하나입니다. 디스커버리는 존재만 알리며, 참여하려면 여전히 페어링이 필요합니다
--tunnel	CC_SERVER_TUNNEL	off	관리형 터널 프로바이더로 off, cloudflared, ngrok, tailscale 중 하나입니다. 공개 노출은 옵트인입니다
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	PATH에서 확인됨	터널 바이너리의 명시적 경로
--tunnel-sha256	CC_SERVER_TUNNEL_SHA256	미설정	해당 바이너리의 예상 SHA-256이며, 실행할 때마다 검증합니다
--tunnel-args	CC_SERVER_TUNNEL_ARGS	비어 있음	터널 실행에 전달할 콤마로 구분된 추가 인수

인덱싱과 서드파티 자격 증명

플래그	환경 변수	기본값	의미
--sandbox	CC_SERVER_SANDBOX	on	백엔드를 사용할 수 있을 때 에이전트 실행을 호스트의 OS 네이티브 샌드박스로 감쌀지 여부입니다. 활성화가 아니라 옵트아웃입니다 — 아래를 참고하십시오
--code-index	CC_SERVER_CODE_INDEX	on	백그라운드 코드 그래프 인덱싱을 위한 운영용 킬 스위치입니다. off로 두면 다시 빌드하지 않고도 깨끗하게 부팅됩니다
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	준비 완료 배너 이후 첫 인덱스 스윕을 미룰 시간(초)입니다(0–300으로 제한)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	하네스 실행이 소수의 상주 도구 세트와 이름 인덱스를 보내고 나머지는 처음 사용할 때 적재할지 여부입니다. 아래를 참고하십시오
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	자격 증명을 처리할 수 없을 때 사람이 고칠 때까지 실행을 보류하는 시간(초)입니다(0–3600으로 제한). 아래를 참고하십시오

자격 증명 값이 비어 있으면 설정되지 않은 것으로 간주되므로 내장 폴백이 그대로 적용됩니다. 소스에서 빌드한 경우에는 내장 자격 증명이 전혀 없습니다.

Google Calendar와 Klipy GIF 선택기는 환경 변수 전용입니다 — --google-client-id / --klipy-app-key 플래그는 없습니다(알 수 없는 플래그는 무시됩니다). GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET 그리고 KLIPY_APP_KEY를 환경에(또는 서버 옆의 .env에) 설정하십시오. 비워 두면 부팅이 실패하는 대신 해당 기능이 비활성화됩니다.

--sandbox

서버는 부팅할 때 호스트를 한 번 탐지하고, 백엔드를 사용할 수 있으면 에이전트 명령 실행을 OS 네이티브 샌드박스로 감쌉니다. macOS에서는 sandbox-exec(Seatbelt), Linux와 WSL2에서는 bwrap과 socat입니다. 아무것도 없는 곳 — Windows, 또는 그 도구들이 없는 Linux 호스트 — 에서는 실행이 환경 정리, 명령 정책, 액션 가드레일로 폴백하며, 시작 로그가 어떤 상태인지 알려 줍니다.

--sandbox off는 탐지가 확인할 수 없는 경우, 즉 샌드박스 프로필 자체가 오작동하는 호스트를 위한 운영용 킬 스위치입니다. 다시 빌드할 필요가 없으며, 서버는 프로세스가 살아 있는 동안 경고를 기록하므로 이 상태가 조용히 지나가는 일은 없습니다.

--tool-deferral

내장 하네스 실행은 소수의 상주 도구 정의 세트와 나머지 도구의 이름만 담은 인덱스를 보내며, 나머지 도구는 처음 사용할 때 스키마를 적재합니다. 이 방식은 도구 블록을 약 78% 줄이고, 항상 보이는 세트를 모델이 도구를 안정적으로 선택하는 범위 안에 유지합니다. 지연된 도구는 실행 내내 이름으로 호출할 수 있고, search_tools가 의도를 기준으로 찾아 줍니다. 도구 컨텍스트와 프롬프트 캐싱을 참고하십시오.

--tool-deferral off를 사용하면 허용된 모든 도구가 다시 상주하게 되어, 서버가 지연이 존재하기 전에 보내던 요청을 그대로 재현합니다. 2계층 표면을 잘 다루지 못하는 모델을 위한 킬 스위치이며, 다시 빌드하는 대신 플래그 하나로 처리합니다. 이는 내장 하네스에만 영향을 줍니다. 외부 클라이언트가 보는 MCP tools/list는 언제나 전체 카탈로그입니다.

--credential-gate

프로바이더 자격 증명이 없거나 소진된 실행은 실패하는 대신 보류됩니다. 운영자에게 이를 고치라는 프롬프트가 표시되고, 고치면 실행이 재개됩니다. 기본 기한은 900초(15분)이며 0–3600으로 제한됩니다.

이 기한은 승인 프롬프트의 기한보다 의도적으로 훨씬 깁니다. 승인은 누군가 몇 초 안에 내리는 결정이지만, 자격 증명을 고치는 일은 터미널을 열고 로그인한 뒤 돌아오는 일이기 때문입니다. 이 상한이 있기 때문에 무인 실행 — 파이프라인 단계, cron 트리거, 웹훅 — 이 잠든 사람을 기다리지 않습니다. 기한이 만료되면 실행은 어차피 실패했을 메시지와 함께 실패합니다.

--credential-gate=0은 킬 스위치입니다. 아무것도 보류되지 않고, 잘못된 자격 증명은 이 게이트가 존재하기 전과 똑같이 해당 턴을 끝냅니다.

하위 명령

명령	하는 일
cc_server	SIGINT/SIGTERM이 올 때까지 서버를 실행합니다
cc_server pair	기기를 프로비저닝하고 그 id와 페어링 키를 출력합니다. 이미 서버가 서비스 중인 데이터 디렉터리에도 안전합니다 — 실행 중인 서버가 재시작 없이 새 기기를 인식합니다
cc_server calendar connect --workspace <id>	기기 코드 흐름으로 Google 계정을 워크스페이스에 연결한 뒤 종료합니다
cc_server update	더 새로운 독립 실행형 릴리스가 있는지 확인하고 내려받아 검증합니다
cc_server --version	빌드 버전과 git SHA를 출력합니다 — /healthz와 RPC 핸드셰이크가 알리는 것과 동일한 아이덴티티입니다

pair

플래그	기본값	의미
--device	web-client	기기 id입니다. 플랫폼은 이 값에서 추론되므로 --device desktop은 데스크톱 행을, --device ios/android는 휴대폰 행을 만듭니다. 그 밖의 값은 웹으로 취급됩니다
--label	플랫폼 이름과 이 머신의 호스트 이름	기기 목록에 표시되는 이름
--host	localhost, 또는 모든 인터페이스에 바인딩된 경우 <this-host>	출력되는 URL에 넣을 호스트입니다. 클라이언트가 실제로 접속할 LAN IP 또는 터널 호스트로 설정하십시오
--client-url	미설정	호스팅된 웹 클라이언트의 오리진입니다. 스캔 가능한 딥 링크와 터미널 QR을 추가합니다

pair는 핵심 --data-dir, --port, --bind 플래그도 받습니다. 이들은 기록할 데이터 디렉터리를 선택하고 출력되는 서버 URL의 형태를 정합니다(루프백에서는 ws, --bind any일 때는 wss). 같은 --device로 pair를 다시 실행하면 그 기기의 키가 교체되고 해당 기기의 활성 세션이 끊깁니다. 여기서 발급한 자격 증명은 앱 내 페어링이 설정하는 30일과 달리 만료가 없습니다.

--client-url QR은 휴대폰 QR이 아닙니다

pair --client-url은 웹 클라이언트의 연결 양식을 채웁니다(서버 URL, 기기 id, 키를 URL 프래그먼트에 담습니다). 휴대폰은 앱 내 페어링 패널에서 발급하는 다른 페이로드, 즉 서버의 전체 연결 디스크립터와 만료 시간으로 페어링합니다. 둘은 서로 호환되지 않습니다 — 기기 페어링을 참고하십시오.

update

--apply는 설치를 교체합니다. 구성된 포트에서 서버가 아직 응답하는 동안에는 --force를 전달하지 않는 한 거부됩니다. --allow-downgrade는 더 오래된 릴리스도 허용합니다.

이 명령은 자신이 소유하지 않은 설치에 대해서는 오류가 아니라 설명과 함께 아예 거부합니다:

환경	감지 방법	안내 내용
데스크톱에 내장된 서버	CC_EMBEDDED=1 또는 CC_BOOTSTRAP_DEVICE_ID	대신 앱을 업데이트하십시오 — 설치 프로그램이 트리 전체를 교체합니다
dart run 소스 체크아웃	스크립트 경로가 .dart로 끝남	git으로 업데이트하십시오
Docker	컨테이너 마커	더 새로운 이미지를 받으십시오

프로세스 수명주기

cc_server는 SIGINT / SIGTERM이 올 때까지 실행됩니다. 이 동작을 제어하는 환경 변수가 하나 더 있으며, 이는 사용자가 아니라 데스크톱이 설정합니다:

변수	효과
CC_EXIT_WITH_PARENT=1	부모 프로세스가 종료될 때 서버도 종료되며, 이는 부모가 자신의 stdin 파이프 쓰기 끝을 닫는 것으로 감지합니다. 데스크톱이 이 변수를 설정하므로 앱이 충돌해도 데이터 디렉터리를 붙잡은 고아 서버가 남지 않습니다

cc_server를 자식 프로세스로 감독하면서 같은 보장을 원하는 경우에만 직접 설정하십시오.

데이터 디렉터리 레이아웃

기본 데이터 디렉터리는 macOS에서 ~/Library/Application Support/control-center, Windows에서 %APPDATA%\control-center, 그 밖의 환경에서는 $XDG_DATA_HOME/control-center(없으면 ~/.local/share/control-center)입니다. 현재 작업 디렉터리 기준 .cc_server는 홈이나 앱 데이터 디렉터리를 확인할 수 없을 때만 사용됩니다.

경로	내용
global.db	워크스페이스 레지스트리, 사용자, 페어링된 기기, 뉴스피드, 플릿 큐
<workspaceId>/workspace.db	워크스페이스마다 하나씩 있는 데이터베이스 — 에이전트, 스페이스, 티켓, 메모리, 코드 그래프
<workspaceId>/chat_credentials/	채팅 봇 토큰이며 평문 JSON으로 저장되어 워크스페이스와 함께 이동합니다
secrets.json	페어링 키, 프로바이더 앱 아이덴티티, 사용자별 토큰과 Google 토큰, SSO(0600)
backups/<timestamp>/	설치 스냅샷 하나 — manifest.json, global.db, 각 워크스페이스의 사본
backups/exports/	단일 워크스페이스 내보내기, <workspaceId>-<timestamp>.db
backups/transfer/	백업 다운로드와 업로드를 위한 스테이징 영역이며, 이를 기록하는 라우트가 정리합니다
models/	온디바이스 임베딩, 화자 분리, 음성 모델
meetings/<meetingId>/	보관된 회의 오디오
rigs/images/	가져온 리그 디스크 이미지(QEMU 데스크톱 화면)
rigs/smolvm/<rigId>/	리그별 microVM 런타임 상태(브로커 시크릿, 0600)
rigs/smolvm-packs/	미리 추출된 머신 팩 — 리그를 반복해서 부팅할 때 속도를 높여 주는 캐시
rigs/tls/	리그 HTTPS를 위한 개발 도메인 인증 기관(키 0600)
rigs/run/<rigId>/	QEMU 오버레이, 시드 이미지, VM별 키(0600)

관련 항목

• 헤드리스 서버 실행 — 이 플래그들이 속한 설정 절차
• 플릿 워커 실행 — 이 서버에 등록하는 별도의 cc_worker 바이너리
• 백업 및 복원 — 이 디렉터리를 안전한 곳에 복사하기
• 백업, 내보내기, 가져오기 — 스냅샷 레이아웃과 모든 백업 작업
• 원격 서버 연결 — 클라이언트를 서버로 향하게 하기
• 배포와 클라이언트 — 서버가 모든 것을 소유하는 이유