Перейти к содержимому
Control Center
Добавить звезду репозиторию5Скачать
Меню

CLI cc_server

Каждый параметр процесса задаётся либо флагом CLI, либо переменной окружения; флаг имеет приоритет, затем переменная окружения, затем значение по умолчанию. Исключение — учётные данные сторонних сервисов, о них ниже.

Основные параметры

Заголовок раздела «Основные параметры»
Флаг Переменная окружения По умолчанию Назначение
--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»
Флаг Переменная окружения По умолчанию Назначение
--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 Объявление в локальной сети: 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 Отправляют ли запуски харнесса небольшой резидентный набор инструментов плюс индекс имён, загружая остальное при первом использовании. См. ниже
--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»

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

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

--tool-deferral

Заголовок раздела «--tool-deferral»

Запуски встроенного харнесса отправляют небольшой резидентный набор определений инструментов плюс индекс остальных, содержащий только имена; схемы загружаются при первом использовании. Это сокращает блок инструментов примерно на 78 % и удерживает всегда видимый набор в пределах, где модели надёжно выбирают инструменты. Отложенные инструменты всё это время остаются вызываемыми по имени, а search_tools находит их по смыслу. См. Контекст инструментов и кэш промптов.

--tool-deferral off снова делает резидентным каждый допущенный инструмент, порождая ровно те запросы, которые сервер делал до появления отложенной загрузки. Это аварийный выключатель для модели, которая плохо справляется с двухуровневой поверхностью, — флаг, а не пересборка. Он затрагивает только встроенный харнесс; tools/list MCP, который видят внешние клиенты, всегда содержит полный каталог.

--credential-gate

Заголовок раздела «--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

Заголовок раздела «pair»
Флаг По умолчанию Назначение
--device web-client Id устройства. Платформа выводится из него, поэтому --device desktop создаёт строку рабочего стола, а --device ios/android — строку телефона; всё остальное считается вебом
--label имя платформы плюс имя хоста этой машины Отображаемое имя в списке устройств
--host localhost или <this-host> при привязке ко всем интерфейсам Хост, который подставляется в напечатанный URL. Задайте IP в локальной сети или хост туннеля, к которому клиент будет обращаться на самом деле
--client-url не задано Источник размещённого веб-клиента. Добавляет ссылку, которую можно отсканировать, и QR-код в терминале

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

update

Заголовок раздела «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 как за дочерним процессом и хотите такой же гарантии.

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

Заголовок раздела «Структура каталога данных»

Каталог данных по умолчанию — ~/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)

См. также

Заголовок раздела «См. также»

Настройки документации

Оформление
Язык
Русский (Россия)