CLI cc_server

Кожен параметр процесу задається або прапорцем CLI, або змінною середовища; пріоритет має прапорець, далі змінна середовища, далі типове значення. Виняток — облікові дані сторонніх сервісів: див. нижче.

Невідомі прапорці ігноруються мовчки

Синтаксичний аналізатор аргументів написано вручну, і він пропускає все, що не розпізнає, тож одрук (--tls-key-file, --bindany) не дає помилки — сервер просто запускається зі значенням за замовчуванням. Перевіряйте рядки журналу запуску, коли прапорець, здається, не діє.

Основні

Прапорець	Змінна	Типово	Значення
--data-dir	CC_SERVER_DATA_DIR	каталог даних застосунку для користувача в ОС (див. нижче)	Бази даних, секрети, моделі та кешовані медіа
--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	вимкнено	Дозволяє прив’язку не до loopback без шифрування. Лише за зворотним проксі, що завершує TLS, у довіреній мережі; ігнорується, коли TLS налаштовано
--public-url	CC_SERVER_PUBLIC_URL	похідний від прив’язки	URL RPC, який цей сервер повідомляє прив’язаним клієнтам. Задайте його явно за проксі, NAT або тунелем — типове значення лише вгадує локальну прив’язку
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	Розділені комами джерела браузера, яким дозволено звертатися до /rpc з інших джерел. Loopback і нативні клієнти дозволені завжди
--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 (лише коли прив’язка не до loopback), 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	Чи загортають запуски агентів у рідну для ОС хоста пісочницю, коли вона доступна. Це радше відмова, ніж увімкнення — див. нижче
--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	Чи надсилають запуски harness невеликий резидентний набір інструментів плюс індекс назв, завантажуючи решту при першому використанні. Див. нижче
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	Скільки секунд запуск стоїть припаркований, чекаючи, поки людина виправить облікові дані, які не можуть його обслужити (обмежено 0–3600). Див. нижче

Порожнє значення облікових даних читається як не задане, тож вбудований запасний варіант усе одно діє. Збірка з вихідного коду взагалі не містить вбудованих облікових даних.

Google Calendar і засіб вибору GIF від Klipy працюють лише через змінні середовища — прапорців --google-client-id / --klipy-app-key немає (невідомі прапорці ігноруються). Задайте GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET і KLIPY_APP_KEY у середовищі (або в .env поряд із сервером). Порожнє значення вимикає цю функцію, а не зриває запуск.

--sandbox

Сервер зондує хост один раз під час запуску й загортає виконання команд агента в рідну для ОС пісочницю, коли доступний бекенд: sandbox-exec (Seatbelt) на macOS, bwrap разом із socat у Linux і WSL2. Там, де його немає — у Windows або на Linux-хості без цих інструментів, — запуски переходять на санітизацію середовища, політику команд та обмеження дій, а журнал запуску повідомляє, який стан застосовано.

--sandbox off — це аварійний вимикач на місці для випадку, якого зондування не бачить: хоста, де сама поведінка профілю пісочниці збоїть. Він не потребує перезбірки, а сервер пише попередження протягом усього часу роботи процесу, тож цей стан ніколи не лишається непоміченим.

--tool-deferral

Запуски вбудованого harness надсилають невеликий резидентний набір визначень інструментів плюс індекс назв решти, які завантажують свої схеми при першому використанні. Це скорочує блок інструментів приблизно на 78% і вкладає постійно видимий набір у смугу, де моделі надійно обирають інструменти. Відкладені інструменти й далі можна викликати за назвою, а search_tools знаходить їх за наміром. Див. Контекст інструментів і кеш промптів.

--tool-deferral off знову робить резидентним кожен допущений інструмент, відтворюючи запити, які сервер робив до появи відкладення. Це аварійний вимикач для моделі, яка погано поводиться з дворівневою поверхнею, — прапорець, а не перезбірка. Він впливає лише на вбудований harness; поверхня MCP tools/list, яку бачать зовнішні клієнти, завжди містить повний каталог.

--credential-gate

Запуск, у якого облікові дані провайдера відсутні або вичерпані, припарковують, а не провалюють: оператор отримує запит виправити їх, і запуск відновлюється, якщо він це зробить. Типовий граничний термін — 900 секунд (15 хвилин), обмежений діапазоном 0–3600.

Цей термін навмисно значно довший за термін запиту на схвалення: схвалення — це рішення, яке людина ухвалює за секунди, а виправлення облікових даних означає відкрити термінал, увійти й повернутися. Саме стеля не дає запуску без нагляду — кроку конвеєра, тригера cron, вебхука — чекати на когось, хто спить. Коли термін спливає, запуск падає з тим самим повідомленням, з яким упав би й так.

--credential-gate=0 — це аварійний вимикач: нічого ніколи не паркують, і погані облікові дані завершують хід точно так, як це було до появи цієї брами.

Підкоманди

Команда	Що робить
cc_server	Запускає сервер до SIGINT/SIGTERM
cc_server pair	Створює пристрій і друкує його ідентифікатор і ключ спарювання. Безпечно щодо каталогу даних, який сервер уже обслуговує — запущений сервер підхоплює пристрій без перезапуску
cc_server calendar connect --workspace <id>	Підключає обліковий запис Google до робочого простору через потік із кодом пристрою, а тоді завершується
cc_server update	Перевіряє наявність, завантажує й перевіряє новіший автономний випуск
cc_server --version	Друкує версію збірки та git SHA — той самий ідентифікатор, який оголошують /healthz і рукостискання RPC

pair

Прапорець	Типово	Значення
--device	web-client	Ідентифікатор пристрою. Платформа виводиться з нього, тож --device desktop створює рядок десктопа, а --device ios/android — рядок телефона; будь-що інше вважається вебклієнтом
--label	назва платформи плюс ім’я хоста цієї машини	Показувана назва у списку пристроїв
--host	localhost або <this-host>, коли прив’язка до всіх інтерфейсів	Хост, який вбудовують у надрукований URL. Задайте його як IP-адресу в LAN або хост тунелю, до якого клієнт справді звертатиметься
--client-url	не задано	Джерело розміщеного вебклієнта. Додає глибоке посилання для сканування та QR-код у терміналі

pair також приймає основні прапорці --data-dir, --port і --bind: вони вибирають каталог даних для запису та формують надрукований URL сервера (ws на loopback, wss при --bind any). Повторний запуск pair для того самого --device оновлює його ключ і розриває активні сесії цього пристрою. Створені тут облікові дані не мають терміну дії, на відміну від 30 днів, які задає спарювання в застосунку.

QR-код --client-url — не телефонний QR

pair --client-url заповнює форму підключення вебклієнта (URL сервера, ідентифікатор пристрою та ключ у фрагменті URL). Телефон спарюється з іншим навантаженням, яке створюють у панелі спарювання в застосунку, — повний дескриптор з’єднання із сервером плюс термін дії. Ці два не взаємозамінні — див. Прив’язати пристрій.

update

--apply замінює інсталяцію; його відхиляють, поки сервер усе ще відповідає на налаштованому порту, якщо ви не передасте --force. --allow-downgrade дозволяє старіший випуск.

Для інсталяцій, якими вона не володіє, команда відмовляється одразу — з поясненням, а не помилкою:

Середовище	Виявляється за	Що вона каже
Вбудований сервер настільного застосунку	CC_EMBEDDED=1 або CC_BOOTSTRAP_DEVICE_ID	Натомість оновіть застосунок — інсталятор замінює все дерево
Checkout джерел для dart run	шлях скрипту закінчується на .dart	Оновіть його через git
Docker	маркери контейнера	Завантажте новіший образ

Життєвий цикл процесу

cc_server працює до SIGINT / SIGTERM. Цим керує ще одна змінна середовища, і її задає настільний застосунок, а не ви:

Змінна	Вплив
CC_EXIT_WITH_PARENT=1	Сервер завершується, коли завершується його батьківський процес; це визначають за тим, що батько закриває кінець запису власного каналу stdin. Настільний застосунок задає її, щоб застосунок, який упав, ніколи не залишив осиротілого сервера, що тримає каталог даних

Задавайте її самостійно, лише якщо ви наглядаєте за cc_server як за дочірнім процесом і хочете такої самої гарантії.

Структура каталогу даних

Типовий каталог даних — ~/Library/Application Support/control-center на macOS, %APPDATA%\control-center у Windows і $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/	Імпортовані дискові образи rig (поверхня десктопа QEMU)
rigs/smolvm/<rigId>/	Стан виконання microVM для кожного rig (секрет брокера, 0600)
rigs/smolvm-packs/	Попередньо розпаковані пакети машин — кеш, який робить повторні завантаження rig швидкими
rigs/tls/	Центр сертифікації dev-домену для HTTPS rig (ключі 0600)
rigs/run/<rigId>/	Оверлеї QEMU, seed-образи та ключі для кожної ВМ (0600)

Див. також

• Запустити headless-сервер — рецепт налаштування, до якого належать ці прапорці
• Запустити воркер флоту — окремий бінарник cc_worker, який реєструється на цьому сервері
• Резервне копіювання та відновлення — копіювання цього каталогу в безпечне місце
• Резервне копіювання, експорт і імпорт — структура знімка та кожна операція резервного копіювання
• Під’єднатися до віддаленого сервера — як спрямувати на нього клієнт
• Розгортання та клієнти — чому сервер володіє всім