CLI cc_server

Mọi cờ của tiến trình nhận một cờ CLI hoặc một biến môi trường; cờ thắng, rồi đến biến môi trường, rồi đến giá trị mặc định. Thông tin xác thực của bên thứ ba là ngoại lệ — xem bên dưới.

Cốt lõi

Cờ	Biến môi trường	Mặc định	Ý nghĩa
`--data-dir`	`CC_SERVER_DATA_DIR`	thư mục dữ liệu ứng dụng theo từng người dùng của hệ điều hành (xem bên dưới)	Cơ sở dữ liệu, bí mật, mô hình và nội dung đa phương tiện được lưu đệm
`--port`	`CC_SERVER_PORT`	`9030`	Cổng TCP (`0` = tạm thời)
`--bind`	`CC_SERVER_BIND`	`loopback`	`loopback`, hoặc `any`/`all`/`0.0.0.0` cho mọi giao diện (cần TLS hoặc `--insecure`)
`--repo-roots`	`CC_SERVER_REPO_ROOTS`	thư mục home của người dùng chạy máy chủ	Các thư mục gốc phân tách bằng dấu phẩy mà máy khách được phép duyệt khi đăng ký một kho mã. Việc duyệt lên trên một thư mục gốc sẽ bị từ chối
`--log-level`	`CC_SERVER_LOG_LEVEL`	`warning`	`debug`, `info`, `warning` hoặc `error`. Các dòng khởi động/sẵn sàng luôn được in
`--server-name`	`CC_SERVER_NAME`	hostname của máy	Tên hiển thị trong các bộ chọn, tính năng khám phá và các bề mặt ghép nối

Khả năng với tới và TLS

Cờ	Biến môi trường	Mặc định	Ý nghĩa
`--tls-cert`	`CC_SERVER_TLS_CERT`	chưa đặt	Chuỗi chứng chỉ PEM. Phục vụ `wss://` ngay trong tiến trình khi được đặt cùng với khóa
`--tls-key`	`CC_SERVER_TLS_KEY`	chưa đặt	Khóa riêng PEM khớp với chứng chỉ
`--insecure`	`CC_SERVER_INSECURE`	tắt	Cho phép bind không phải loopback ở dạng thuần. Chỉ dùng phía sau một proxy kết thúc TLS trên một mạng tin cậy; bị bỏ qua khi TLS đã được cấu hình
`--public-url`	`CC_SERVER_PUBLIC_URL`	được suy ra từ bind	URL RPC mà máy chủ này quảng bá cho các máy khách đã ghép nối. Hãy đặt tường minh khi đứng sau proxy, NAT hoặc tunnel — giá trị mặc định chỉ là phỏng đoán từ bind cục bộ
`--allowed-origins`	`CC_SERVER_ALLOWED_ORIGINS`	`https://app.usectrl.dev`	Các origin trình duyệt phân tách bằng dấu phẩy được phép gọi `/rpc` khác origin. Loopback và các máy khách native luôn được phép
`--web-client-url`	`CC_SERVER_WEB_CLIENT_URL`	chưa đặt	Origin của máy khách web được lưu trữ mà các callback đăng nhập một lần quay về
`--signaling-url`	`CC_SERVER_SIGNALING_URL`	`wss://signaling.usectrl.dev`	Bộ môi giới relay mà máy chủ này tham gia để một chiếc điện thoại có thể với tới nó khi không có đường trực tiếp
`--mdns`	`CC_SERVER_MDNS`	`auto`	Quảng bá trên LAN: `auto` (chỉ khi bind ra ngoài loopback), `on`, `off`. Tính năng khám phá chỉ quảng bá sự tồn tại — tham gia vẫn cần ghép nối
`--tunnel`	`CC_SERVER_TUNNEL`	`off`	Nhà cung cấp tunnel được quản lý: `off`, `cloudflared`, `ngrok`, `tailscale`. Việc phơi ra công khai phải do người dùng chủ động bật
`--tunnel-binary`	`CC_SERVER_TUNNEL_BINARY`	được phân giải từ `PATH`	Đường dẫn tường minh tới tệp nhị phân tunnel
`--tunnel-sha256`	`CC_SERVER_TUNNEL_SHA256`	chưa đặt	SHA-256 mong đợi của tệp nhị phân đó, được kiểm tra trước mỗi lần sinh tiến trình
`--tunnel-args`	`CC_SERVER_TUNNEL_ARGS`	rỗng	Các đối số bổ sung phân tách bằng dấu phẩy cho lệnh gọi tunnel

Lập chỉ mục và thông tin xác thực bên thứ ba

Cờ	Biến môi trường	Mặc định	Ý nghĩa
`--sandbox`	`CC_SERVER_SANDBOX`	`on`	Liệu các lượt chạy agent có được bọc trong sandbox native của hệ điều hành trên máy chủ nhà khi có sẵn hay không. Đây là cách chủ động tắt chứ không phải cách bật — xem bên dưới
`--code-index`	`CC_SERVER_CODE_INDEX`	`on`	Công tắc tắt cho môi trường thật đối với việc lập chỉ mục đồ thị mã chạy nền. `off` khởi động sạch mà không cần dựng lại
`--code-index-defer`	`CC_SERVER_CODE_INDEX_DEFER`	`15`	Số giây giữ lần quét chỉ mục đầu tiên sau banner báo sẵn sàng (giới hạn trong khoảng 0–300)
`--tool-deferral`	`CC_SERVER_TOOL_DEFERRAL`	`on`	Liệu các lượt chạy harness có gửi một tập công cụ thường trú nhỏ cộng một chỉ mục tên, phần còn lại được nạp ở lần dùng đầu tiên hay không. Xem bên dưới
`--credential-gate`	`CC_SERVER_CREDENTIAL_GATE`	`900`	Số giây một lượt chạy tạm dừng chờ người sửa một thông tin xác thực không thể phục vụ nó (giới hạn trong khoảng 0–3600). Xem bên dưới

Giá trị rỗng cho một thông tin xác thực được hiểu là chưa đặt, nên phương án dự phòng tích hợp sẵn vẫn được áp dụng. Một bản dựng từ mã nguồn hoàn toàn không mang theo thông tin xác thực tích hợp nào.

Google Calendar và bộ chọn GIF Klipy chỉ có qua biến môi trường — không có cờ --google-client-id / --klipy-app-key (các cờ không xác định bị bỏ qua). Hãy đặt GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET và KLIPY_APP_KEY trong môi trường (hoặc một tệp .env bên cạnh máy chủ). Giá trị rỗng sẽ tắt tính năng đó thay vì khiến quá trình khởi động thất bại.

`--sandbox`

Máy chủ dò máy chủ nhà một lần lúc khởi động và bọc việc thực thi lệnh của agent trong sandbox native của hệ điều hành khi có backend: sandbox-exec (Seatbelt) trên macOS, bwrap cùng socat trên Linux và WSL2. Ở nơi không có backend nào — Windows, hoặc một máy chủ nhà Linux thiếu những công cụ đó — các lượt chạy lùi về việc làm sạch môi trường, chính sách lệnh và các rào chắn hành động, và nhật ký khởi động cho biết trạng thái nào đang áp dụng.

--sandbox off là công tắc tắt cho môi trường thật dành cho trường hợp mà phép dò không thấy được: một máy chủ nhà nơi chính hồ sơ sandbox cư xử sai. Nó không cần dựng lại và máy chủ ghi một cảnh báo suốt vòng đời tiến trình để trạng thái đó không bao giờ im lặng.

`--tool-deferral`

Các lượt chạy của harness tích hợp sẵn gửi một tập định nghĩa công cụ thường trú nhỏ cộng một chỉ mục chỉ gồm tên của phần còn lại; các định nghĩa này nạp lược đồ của chúng ở lần đầu được dùng. Cách này cắt khối công cụ đi khoảng 78% và giữ tập luôn hiển thị nằm trong khoảng mà các mô hình chọn công cụ một cách đáng tin cậy. Các công cụ bị trì hoãn vẫn gọi được bằng tên trong suốt quá trình, và search_tools tìm thấy chúng theo ý định. Xem Ngữ cảnh công cụ và bộ nhớ đệm prompt.

--tool-deferral off khiến mọi công cụ được chấp nhận trở lại thường trú, tái tạo đúng những yêu cầu mà máy chủ gửi trước khi có tính năng trì hoãn. Đây là công tắc tắt dành cho một mô hình xử lý kém bề mặt hai tầng — một cờ thay vì một lần dựng lại. Nó chỉ ảnh hưởng đến harness tích hợp sẵn; tools/list của MCP mà các máy khách bên ngoài thấy luôn là danh mục đầy đủ.

`--credential-gate`

Một lượt chạy thiếu thông tin xác thực của nhà cung cấp hoặc đã dùng hết sẽ bị tạm dừng thay vì thất bại: người vận hành nhận được lời nhắc sửa nó, và lượt chạy tiếp tục nếu họ làm vậy. Hạn chót mặc định là 900 giây (15 phút), được giới hạn trong khoảng 0–3600.

Hạn chót này cố tình dài hơn nhiều so với lời nhắc phê duyệt: một phê duyệt là quyết định ai đó đưa ra trong vài giây, còn sửa một thông tin xác thực nghĩa là mở terminal, đăng nhập rồi quay lại. Chính mức trần này giữ cho một lượt chạy không người trông coi — một bước quy trình, một trình kích hoạt cron, một webhook — không phải chờ đợi một người đang ngủ. Khi hết hạn, lượt chạy thất bại với đúng thông báo mà nó vốn sẽ thất bại.

--credential-gate=0 là công tắc tắt: không gì bị tạm dừng và một thông tin xác thực hỏng kết thúc lượt đúng như trước khi có cổng này.

Lệnh con

Lệnh	Tác dụng
`cc_server`	Chạy máy chủ cho tới khi nhận `SIGINT`/`SIGTERM`
`cc_server pair`	Cấp phát một thiết bị và in ra id cùng khóa ghép nối của nó. An toàn khi thư mục dữ liệu đang được một máy chủ phục vụ — máy chủ đang chạy sẽ nhận thiết bị mà không cần khởi động lại
`cc_server calendar connect --workspace <id>`	Kết nối một tài khoản Google với một không gian làm việc qua luồng mã thiết bị, rồi thoát
`cc_server update`	Kiểm tra, tải về và xác minh một bản phát hành độc lập mới hơn
`cc_server --version`	In phiên bản bản dựng và SHA git — đúng danh tính mà `/healthz` và bước bắt tay RPC quảng bá

`pair`

Cờ	Mặc định	Ý nghĩa
`--device`	`web-client`	Id thiết bị. Nền tảng được suy ra từ nó, nên `--device desktop` tạo ra một hàng desktop còn `--device ios`/`android` một hàng điện thoại; mọi giá trị khác được coi là web
`--label`	tên nền tảng cộng hostname của máy này	Tên hiển thị trong danh sách thiết bị
`--host`	`localhost`, hoặc `<this-host>` khi bind ra mọi giao diện	Host cần nhúng vào URL được in ra. Hãy đặt nó thành IP LAN hoặc host tunnel mà máy khách thực sự sẽ gọi tới
`--client-url`	chưa đặt	Origin của máy khách web được lưu trữ. Thêm một liên kết sâu quét được và mã QR cho terminal

pair cũng chấp nhận các cờ cốt lõi --data-dir, --port và --bind: chúng chọn thư mục dữ liệu để ghi vào và định hình URL máy chủ được in ra (ws trên loopback, wss khi --bind any). Chạy lại pair cho cùng một --device sẽ xoay khóa của nó và hủy các phiên đang hoạt động của thiết bị đó. Thông tin xác thực được phát hành ở đây không có thời hạn, khác với 30 ngày mà một lần ghép nối trong ứng dụng đặt ra.

`update`

--apply thay thế bản cài đặt; nó bị từ chối khi vẫn còn một máy chủ trả lời trên cổng đã cấu hình, trừ khi bạn truyền --force. --allow-downgrade cho phép một bản phát hành cũ hơn.

Lệnh này từ chối thẳng, kèm lời giải thích thay vì một lỗi, đối với những bản cài đặt mà nó không sở hữu:

Môi trường	Phát hiện bằng	Thông báo
Máy chủ nhúng của ứng dụng máy tính	`CC_EMBEDDED=1` hoặc `CC_BOOTSTRAP_DEVICE_ID`	Hãy cập nhật ứng dụng thay vào đó — trình cài đặt thay thế toàn bộ cây thư mục
Một bản checkout mã nguồn chạy bằng `dart run`	đường dẫn script kết thúc bằng `.dart`	Hãy cập nhật nó bằng git
Docker	các dấu hiệu nhận biết container	Hãy kéo về một ảnh mới hơn

Vòng đời tiến trình

cc_server chạy cho tới khi nhận SIGINT / SIGTERM. Một biến môi trường bổ sung chi phối điều đó, và nó được ứng dụng máy tính đặt chứ không phải bạn:

Biến	Tác dụng
`CC_EXIT_WITH_PARENT=1`	Máy chủ thoát khi tiến trình cha của nó thoát, được phát hiện qua việc tiến trình cha đóng đầu ghi của đường ống stdin. Ứng dụng máy tính đặt nó để một ứng dụng gặp sự cố không bao giờ bỏ lại một máy chủ mồ côi đang giữ thư mục dữ liệu

Chỉ tự đặt nó nếu bạn đang giám sát cc_server như một tiến trình con và muốn có cùng bảo đảm đó.

Bố cục thư mục dữ liệu

Thư mục dữ liệu mặc định là ~/Library/Application Support/control-center trên macOS, %APPDATA%\control-center trên Windows và $XDG_DATA_HOME/control-center (nếu không thì ~/.local/share/control-center) ở những nơi khác. Một .cc_server tương đối theo cwd chỉ được dùng khi không phân giải được thư mục home hay thư mục dữ liệu ứng dụng nào.

Đường dẫn	Nội dung
`global.db`	Sổ đăng ký không gian làm việc, người dùng, thiết bị đã ghép nối, bảng tin và hàng đợi đội máy
`<workspaceId>/workspace.db`	Một cơ sở dữ liệu cho mỗi không gian làm việc — agent, space, phiếu, bộ nhớ, đồ thị mã
`<workspaceId>/chat_credentials/`	Token bot chat, dưới dạng JSON thuần, để chúng đi kèm không gian làm việc
`secrets.json`	Khóa ghép nối, danh tính ứng dụng của nhà cung cấp, token theo từng người dùng và token Google, SSO (`0600`)
`backups/<timestamp>/`	Một ảnh chụp nhanh bản cài đặt — `manifest.json`, `global.db` và một bản sao của từng không gian làm việc
`backups/exports/`	Bản xuất của một không gian làm việc, `<workspaceId>-<timestamp>.db`
`backups/transfer/`	Khu trung chuyển cho việc tải lên và tải xuống bản sao lưu; được dọn bởi tuyến ghi vào đó
`models/`	Mô hình embedding, tách người nói và nhận dạng giọng nói chạy ngay trên máy
`meetings/<meetingId>/`	Âm thanh cuộc họp được lưu giữ
`rigs/images/`	Ảnh đĩa rig đã nhập (bề mặt desktop QEMU)
`rigs/smolvm/<rigId>/`	Trạng thái chạy microVM của từng rig (bí mật của broker, `0600`)
`rigs/smolvm-packs/`	Gói máy đã giải nén sẵn — bộ nhớ đệm giúp các lần khởi động rig lặp lại nhanh chóng
`rigs/tls/`	CA (nhà cấp phát chứng chỉ) của tên miền dev dùng cho HTTPS của rig (khóa `0600`)
`rigs/run/<rigId>/`	Lớp phủ QEMU, ảnh seed và khóa của từng VM (`0600`)

Xem thêm

Chạy máy chủ không giao diện — công thức thiết lập mà những cờ này thuộc về
Chạy một worker đội máy — tệp nhị phân cc_worker riêng biệt đăng ký với máy chủ này
Sao lưu và khôi phục — sao chép thư mục này tới một nơi an toàn
Sao lưu, xuất và nhập — bố cục ảnh chụp nhanh và mọi thao tác sao lưu
Kết nối máy chủ từ xa — trỏ một máy khách tới đó
Triển khai và máy khách — vì sao máy chủ sở hữu mọi thứ