CLI cc_server

Każde ustawienie procesu można podać flagą CLI albo zmienną środowiskową; pierwszeństwo ma flaga, potem zmienna środowiskowa, a na końcu wartość domyślna. Wyjątkiem są poświadczenia firm trzecich — patrz poniżej.

Nieznane flagi są po cichu ignorowane

Parser argumentów jest napisany ręcznie i pomija wszystko, czego nie rozpoznaje, więc literówka (--tls-key-file, --bindany) nie daje żadnego błędu — serwer po prostu startuje z wartością domyślną. Gdy flaga wydaje się nie działać, sprawdź wiersze logu startowego.

Ustawienia podstawowe

Flaga	Zmienna	Domyślnie	Znaczenie
--data-dir	CC_SERVER_DATA_DIR	katalog danych aplikacji dla użytkownika w systemie (patrz poniżej)	Bazy danych, sekrety, modele i zbuforowane multimedia
--port	CC_SERVER_PORT	9030	Port TCP (0 = efemeryczny)
--bind	CC_SERVER_BIND	loopback	loopback albo any/all/0.0.0.0 dla wszystkich interfejsów (wymaga TLS lub --insecure)
--repo-roots	CC_SERVER_REPO_ROOTS	katalog domowy użytkownika serwera	Rozdzielone przecinkami katalogi bazowe, które klient może przeglądać przy rejestrowaniu repozytorium. Przeglądanie powyżej korzenia jest odrzucane
--log-level	CC_SERVER_LOG_LEVEL	warning	debug, info, warning lub error. Wiersze startu i gotowości są zawsze wypisywane
--server-name	CC_SERVER_NAME	nazwa hosta maszyny	Nazwa pokazywana w selektorach, wykrywaniu i powierzchniach parowania

Osiągalność i TLS

Flaga	Zmienna	Domyślnie	Znaczenie
--tls-cert	CC_SERVER_TLS_CERT	nieustawione	Łańcuch certyfikatów PEM. Razem z kluczem obsługuje wss:// w tym samym procesie
--tls-key	CC_SERVER_TLS_KEY	nieustawione	Klucz prywatny PEM pasujący do certyfikatu
--insecure	CC_SERVER_INSECURE	wyłączone	Zezwala na bindowanie poza loopbackiem bez szyfrowania. Tylko za proxy kończącym TLS w zaufanej sieci; ignorowane, gdy skonfigurowano TLS
--public-url	CC_SERVER_PUBLIC_URL	wyliczany z bindowania	Adres URL RPC, który ten serwer ogłasza sparowanym klientom. Ustaw go jawnie za proxy, NAT lub tunelem — wartość domyślna to jedynie domysł na podstawie lokalnego bindowania
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	Rozdzielone przecinkami pochodzenia przeglądarek, którym wolno łączyć się z /rpc cross-origin. Loopback i klienci natywni są zawsze dozwoleni
--web-client-url	CC_SERVER_WEB_CLIENT_URL	nieustawione	Pochodzenie hostowanego klienta webowego, do którego wracają wywołania zwrotne logowania jednokrotnego
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	Brokerski przekaźnik, do którego dołącza ten serwer, aby telefon mógł do niego dotrzeć bez bezpośredniej ścieżki
--mdns	CC_SERVER_MDNS	auto	Ogłaszanie w sieci LAN: auto (tylko przy bindowaniu poza loopbackiem), on, off. Wykrywanie ogłasza wyłącznie istnienie — dołączenie i tak wymaga parowania
--tunnel	CC_SERVER_TUNNEL	off	Zarządzany dostawca tunelu: off, cloudflared, ngrok, tailscale. Publiczne wystawienie wymaga wyraźnego włączenia
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	ustalany na podstawie PATH	Jawna ścieżka pliku binarnego tunelu
--tunnel-sha256	CC_SERVER_TUNNEL_SHA256	nieustawione	Oczekiwany skrót SHA-256 tego pliku binarnego, weryfikowany przed każdym uruchomieniem
--tunnel-args	CC_SERVER_TUNNEL_ARGS	puste	Rozdzielone przecinkami dodatkowe argumenty wywołania tunelu

Indeksowanie i poświadczenia firm trzecich

Flaga	Zmienna	Domyślnie	Znaczenie
--sandbox	CC_SERVER_SANDBOX	on	Czy uruchomienia agentów są opakowywane w natywny dla systemu hosta sandbox, gdy jest dostępny. Opcja rezygnacji, a nie włączenia — patrz poniżej
--code-index	CC_SERVER_CODE_INDEX	on	Wyłącznik bezpieczeństwa w środowisku produkcyjnym dla indeksowania grafu kodu w tle. off startuje czysto, bez przebudowy
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	Liczba sekund, przez które pierwszy przebieg indeksowania jest wstrzymywany po banerze gotowości (ograniczana do 0–300)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	Czy uruchomienia harnessu wysyłają mały, rezydentny zestaw narzędzi plus indeks nazw, wczytując resztę przy pierwszym użyciu. Patrz poniżej
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	Liczba sekund, przez które uruchomienie czeka, aż człowiek naprawi poświadczenie, które nie może go obsłużyć (ograniczana do 0–3600). Patrz poniżej

Pusta wartość poświadczenia jest odczytywana jako nieustawiona, więc wbudowany mechanizm zapasowy nadal działa. Kompilacja ze źródeł nie zawiera żadnych wbudowanych poświadczeń.

Google Calendar i selektor GIF-ów Klipy działają wyłącznie przez środowisko — nie ma flagi --google-client-id / --klipy-app-key (nieznane flagi są ignorowane). Ustaw GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET oraz KLIPY_APP_KEY w środowisku (albo w pliku .env obok serwera). Pusta wartość wyłącza daną funkcję, zamiast powodować niepowodzenie startu.

--sandbox

Serwer sonduje host raz przy starcie i gdy backend jest dostępny, opakowuje wykonywanie poleceń agentów w natywny dla systemu sandbox: sandbox-exec (Seatbelt) w macOS oraz bwrap i socat w Linuksie i WSL2. Tam, gdzie go nie ma — w Windows albo na hoście z Linuksem bez tych narzędzi — uruchomienia cofają się do oczyszczania środowiska, polityki poleceń i guardrailów akcji, a log startowy mówi, który stan obowiązuje.

--sandbox off to wyłącznik bezpieczeństwa w środowisku produkcyjnym dla przypadku, którego sonda nie widzi: hosta, na którym sam profil sandboxa działa niepoprawnie. Nie wymaga przebudowy, a serwer przez cały czas życia procesu zapisuje ostrzeżenie, więc ten stan nigdy nie pozostaje niemy.

--tool-deferral

Uruchomienia wbudowanego harnessu wysyłają mały, rezydentny zestaw definicji narzędzi plus sam indeks nazw pozostałych, których schematy wczytują się przy pierwszym użyciu. Zmniejsza to blok narzędzi o około 78% i utrzymuje stale widoczny zestaw w przedziale, w którym modele wybierają narzędzia niezawodnie. Odroczone narzędzia przez cały czas można wywołać po nazwie, a search_tools znajduje je po intencji. Zobacz Kontekst narzędzi i cache promptów.

--tool-deferral off ponownie czyni rezydentnym każde dopuszczone narzędzie, odtwarzając żądania, które serwer wysyłał, zanim odroczenie powstało. To wyłącznik bezpieczeństwa dla modelu, który źle radzi sobie z dwuwarstwową powierzchnią — flaga zamiast przebudowy. Dotyczy wyłącznie wbudowanego harnessu; tools/list MCP, który widzą klienci zewnętrzni, to zawsze pełny katalog.

--credential-gate

Uruchomienie, którego poświadczenie dostawcy brakuje lub zostało wyczerpane, trafia do poczekalni, a nie kończy się niepowodzeniem: operator dostaje prośbę o naprawienie go, a uruchomienie wznawia się, jeśli to zrobi. Domyślny termin to 900 sekund (15 minut), ograniczany do 0–3600.

Termin jest celowo znacznie dłuższy niż w przypadku prośby o zatwierdzenie: zatwierdzenie to decyzja, którą podejmuje się w kilka sekund, a naprawienie poświadczenia oznacza otwarcie terminala, zalogowanie się i powrót. To właśnie ten pułap powstrzymuje uruchomienie bez nadzoru — krok potoku, wyzwalacz cron, webhook — przed czekaniem na kogoś, kto śpi. Gdy termin upłynie, uruchomienie kończy się niepowodzeniem z komunikatem, którym i tak by się skończyło.

--credential-gate=0 to wyłącznik bezpieczeństwa: nic nigdy nie trafia do poczekalni, a błędne poświadczenie kończy turę dokładnie tak, jak przed powstaniem tej bramki.

Podpolecenia

Polecenie	Co robi
cc_server	Uruchamia serwer aż do SIGINT/SIGTERM
cc_server pair	Tworzy urządzenie i wypisuje jego identyfikator oraz klucz parowania. Bezpieczne wobec katalogu danych, który serwer już obsługuje — działający serwer przejmuje urządzenie bez restartu
cc_server calendar connect --workspace <id>	Łączy konto Google z obszarem roboczym za pomocą przepływu kodu urządzenia, a następnie kończy działanie
cc_server update	Sprawdza, pobiera i weryfikuje nowsze samodzielne wydanie
cc_server --version	Wypisuje wersję kompilacji i SHA gita — tę samą tożsamość, którą ogłaszają /healthz i uzgadnianie RPC

pair

Flaga	Domyślnie	Znaczenie
--device	web-client	Identyfikator urządzenia. Platforma jest z niego wnioskowana, więc --device desktop tworzy wiersz komputera, a --device ios/android wiersz telefonu; wszystko inne jest traktowane jako klient webowy
--label	nazwa platformy plus nazwa hosta tej maszyny	Nazwa wyświetlana na liście urządzeń
--host	localhost albo <this-host> przy bindowaniu do wszystkich interfejsów	Host osadzany w wypisywanym adresie URL. Ustaw go na adres IP w sieci LAN albo host tunelu, z którym klient faktycznie się połączy
--client-url	nieustawione	Pochodzenie hostowanego klienta webowego. Dodaje link bezpośredni do zeskanowania i kod QR w terminalu

pair przyjmuje też podstawowe flagi --data-dir, --port i --bind: wybierają one katalog danych do zapisu i kształtują wypisywany adres URL serwera (ws na loopbacku, wss przy --bind any). Ponowne uruchomienie pair dla tego samego --device rotuje jego klucz i porzuca aktywne sesje tego urządzenia. Utworzone tu poświadczenie nie wygasa, inaczej niż po 30 dniach ustawianych przez parowanie w aplikacji.

Kod QR z --client-url to nie kod QR telefonu

pair --client-url wypełnia formularz połączenia klienta webowego (adres URL serwera, identyfikator urządzenia i klucz we fragmencie adresu URL). Telefon paruje się z innym ładunkiem, tworzonym w panelu parowania w aplikacji — pełnym deskryptorem połączenia serwera plus terminem ważności. Tych dwóch nie można używać zamiennie — zobacz Sparuj urządzenie.

update

--apply zastępuje instalację; jest odrzucane, dopóki serwer nadal odpowiada na skonfigurowanym porcie, chyba że podasz --force. --allow-downgrade zezwala na starsze wydanie.

W przypadku instalacji, których nie jest właścicielem, polecenie odmawia od razu, podając wyjaśnienie, a nie błąd:

Środowisko	Wykrywane przez	Co mówi
Wbudowany serwer aplikacji desktopowej	CC_EMBEDDED=1 lub CC_BOOTSTRAP_DEVICE_ID	Zaktualizuj zamiast tego aplikację — instalator wymienia całe drzewo
Źródła uruchamiane przez dart run	ścieżka skryptu kończy się na .dart	Zaktualizuj je za pomocą gita
Docker	znaczniki kontenera	Pobierz nowszy obraz

Cykl życia procesu

cc_server działa aż do SIGINT / SIGTERM. Steruje tym jedna dodatkowa zmienna środowiskowa, ustawiana przez aplikację desktopową, a nie przez Ciebie:

Zmienna	Efekt
CC_EXIT_WITH_PARENT=1	Serwer kończy działanie wraz z procesem nadrzędnym; wykrywa się to po zamknięciu przez rodzica końca zapisu jego potoku stdin. Aplikacja desktopowa ustawia ją, aby zawieszona aplikacja nigdy nie pozostawiła osieroconego serwera trzymającego katalog danych

Ustaw ją samodzielnie tylko wtedy, gdy nadzorujesz cc_server jako proces potomny i chcesz mieć tę samą gwarancję.

Układ katalogu danych

Domyślnym katalogiem danych jest ~/Library/Application Support/control-center w macOS, %APPDATA%\control-center w Windows oraz $XDG_DATA_HOME/control-center (w przeciwnym razie ~/.local/share/control-center) gdzie indziej. Względny wobec bieżącego katalogu .cc_server jest używany tylko wtedy, gdy nie da się rozwiązać żadnego katalogu domowego ani katalogu danych aplikacji.

Ścieżka	Zawartość
global.db	Rejestr obszarów roboczych, użytkownicy, sparowane urządzenia, newsfeed i kolejka floty
<workspaceId>/workspace.db	Jedna baza danych na obszar roboczy — agenci, przestrzenie, zgłoszenia, pamięć, graf kodu
<workspaceId>/chat_credentials/	Tokeny botów czatu jako zwykły JSON, dzięki czemu podróżują razem z obszarem roboczym
secrets.json	Klucze parowania, tożsamość aplikacji dostawcy, tokeny poszczególnych użytkowników i tokeny Google, SSO (0600)
backups/<timestamp>/	Jedna migawka instalacji — manifest.json, global.db i kopia każdego obszaru roboczego
backups/exports/	Eksporty pojedynczego obszaru roboczego, <workspaceId>-<timestamp>.db
backups/transfer/	Obszar przejściowy dla pobieranych i wysyłanych kopii zapasowych; czyszczony przez trasę, która do niego zapisuje
models/	Modele osadzania, diaryzacji i mowy działające na urządzeniu
meetings/<meetingId>/	Zachowane nagrania audio spotkań
rigs/images/	Zaimportowane obrazy dysków rigów (powierzchnia pulpitu QEMU)
rigs/smolvm/<rigId>/	Stan wykonawczy microVM poszczególnych rigów (sekret brokera, 0600)
rigs/smolvm-packs/	Wstępnie rozpakowane paczki maszyn — cache, który przyspiesza kolejne starty rigów
rigs/tls/	Urząd certyfikacji domeny deweloperskiej dla HTTPS rigów (klucze 0600)
rigs/run/<rigId>/	Nakładki QEMU, obrazy seed i klucze poszczególnych maszyn wirtualnych (0600)

Zobacz też

• Uruchom serwer headless — przepis konfiguracyjny, do którego należą te flagi
• Uruchom workera floty — osobne binarium cc_worker, które rejestruje się w tym serwerze
• Kopia zapasowa i przywracanie — kopiowanie tego katalogu w bezpieczne miejsce
• Kopia zapasowa, eksport i import — układ migawek i każda operacja kopii zapasowej
• Połącz się ze zdalnym serwerem — kierowanie klienta na taki serwer
• Wdrażanie i klienci — dlaczego serwer jest właścicielem wszystkiego