CLI مربوط به cc_server

هر پرچم فرایند هم به‌شکل یک پرچم خط فرمان و هم یک متغیر محیطی پذیرفته می‌شود؛ اولویت با پرچم است، سپس متغیر محیطی و در آخر مقدار پیش‌فرض. اعتبارنامه‌های سرویس‌های ثالث استثنا هستند — پایین‌تر را ببینید.

پرچم‌های ناشناخته بی‌صدا نادیده گرفته می‌شوند

تجزیه‌گر آرگومان دست‌ساز است و هر چیزی را که نشناسد رد می‌کند، پس یک غلط تایپی (--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	خاموش	اجازهٔ bind متن ساده روی غیر loopback. فقط پشت یک پروکسی مختوم‌کنندهٔ TLS روی شبکه‌ای قابل‌اعتماد؛ وقتی TLS پیکربندی شده باشد نادیده گرفته می‌شود
--public-url	CC_SERVER_PUBLIC_URL	برگرفته از bind	نشانی RPC‌ای که این سرور به کلاینت‌های جفت‌شده اعلام می‌کند. پشت پروکسی، NAT یا تونل این را صریح تنظیم کنید — مقدار پیش‌فرض فقط حدسی از bind محلی است
--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 مورد انتظار آن باینری، که پیش از هر spawn بررسی می‌شود
--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	ثانیه‌هایی که نخستین جاروب نمایه‌سازی پس از بنر آماده‌بودن به تعویق می‌افتد (محدود به ۰–۳۰۰)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	آیا اجراهای هارنس یک مجموعهٔ کوچک ابزار مقیم به‌همراه یک نمایهٔ نامی می‌فرستند و بقیه را در نخستین استفاده بار می‌کنند. پایین را ببینید
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	ثانیه‌هایی که یک اجرا پارک می‌ماند تا انسانی اعتبارنامه‌ای را که نمی‌تواند کارش را بسازد درست کند (محدود به ۰–۳۶۰۰). پایین را ببینید

مقدار خالی برای یک اعتبارنامه، تنظیم‌نشده خوانده می‌شود، پس بازگشت درونی همچنان اعمال می‌شود. ساخت از منبع اصلاً هیچ اعتبارنامهٔ درونی‌ای حمل نمی‌کند.

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

اجراهای هارنس داخلی یک مجموعهٔ کوچک مقیم از تعریف‌های ابزار به‌همراه یک نمایهٔ فقط‌نامی از بقیه می‌فرستند که شِماهایشان را نخستین‌بار که به کار روند بار می‌کنند. این کار بلوک ابزار را حدود ۷۸٪ کوچک می‌کند و مجموعهٔ همیشه‌پیدا را در محدوده‌ای نگه می‌دارد که مدل‌ها در آن ابزارها را قابل‌اتکا انتخاب می‌کنند. ابزارهای به‌تعویق‌افتاده در سراسر اجرا با نام فراخواندنی می‌مانند و search_tools آن‌ها را بر پایهٔ قصد پیدا می‌کند. بافت ابزار و کش پرامپت را ببینید.

--tool-deferral off هر ابزار پذیرفته‌شده را دوباره مقیم می‌کند و همان درخواست‌هایی را بازمی‌سازد که سرور پیش از وجود تعویق می‌فرستاد. این کلید قطع برای مدلی است که سطح دوسطحی را بد اداره می‌کند — یک پرچم، به‌جای یک بازساخت. فقط هارنس داخلی را متأثر می‌کند؛ tools/listی که MCP به کلاینت‌های بیرونی نشان می‌دهد همیشه فهرست کامل است.

--credential-gate

اجرایی که اعتبارنامهٔ ارائه‌دهنده‌اش گم شده یا مصرف شده باشد، به‌جای شکست پارک می‌شود: به اپراتور پیامی داده می‌شود تا آن را درست کند و اگر این کار را بکند، اجرا از سر گرفته می‌شود. مهلت پیش‌فرض ۹۰۰ ثانیه (۱۵ دقیقه) است و به ۰–۳۶۰۰ محدود می‌شود.

این مهلت عامدانه بسیار طولانی‌تر از مهلت پرامپت تأیید است: تأیید تصمیمی است که کسی در چند ثانیه می‌گیرد، در حالی که درست‌کردن یک اعتبارنامه یعنی باز کردن ترمینال، ورود و برگشتن. همین سقف است که نمی‌گذارد یک اجرای بی‌سرپرست — یک گام پایپ‌لاین، یک تریگر cron، یک وبهوک — منتظر کسی بماند که خواب است. وقتی مهلت تمام شود، اجرا با همان پیامی شکست می‌خورد که در هر حال می‌خورد.

--credential-gate=0 کلید قطع است: هیچ‌چیز هرگز پارک نمی‌شود و یک اعتبارنامهٔ بد همان‌طور که پیش از وجود این دروازه نوبت را پایان می‌داد، الان هم پایان می‌دهد.

زیرفرمان‌ها

فرمان	کارش
cc_server	سرور را تا SIGINT/SIGTERM اجرا می‌کند
cc_server pair	دستگاهی را تأمین می‌کند و شناسه و کلید جفت‌سازی‌اش را چاپ می‌کند. در برابر پوشهٔ داده‌ای که سروری همین حالا سرو می‌کند ایمن است — سرور در حال اجرا دستگاه را بدون راه‌اندازی مجدد برمی‌دارد
cc_server calendar connect --workspace <id>	یک حساب Google را از طریق جریان کد دستگاه به یک فضای کاری متصل می‌کند و سپس خارج می‌شود
cc_server update	یک نسخهٔ مستقل تازه‌تر را بررسی، دانلود و تأیید می‌کند
cc_server --version	نسخهٔ ساخت و SHA گیت را چاپ می‌کند — همان هویتی که /healthz و دست‌دادن RPC اعلام می‌کنند

pair

پرچم	پیش‌فرض	معنا
--device	web-client	شناسهٔ دستگاه. پلتفرم از روی آن استنباط می‌شود، پس --device desktop یک سطر رومیزی و --device ios/android یک سطر تلفن می‌سازد؛ هر چیز دیگری وب در نظر گرفته می‌شود
--label	نام پلتفرم به‌همراه نام میزبان این ماشین	نام نمایشی در فهرست دستگاه‌ها
--host	localhost، یا <this-host> وقتی به همهٔ واسط‌ها مقید شده باشد	میزبانی که در نشانی چاپ‌شده جای می‌گیرد. آن را روی IP شبکهٔ محلی یا میزبان تونلی بگذارید که کلاینت واقعاً با آن تماس می‌گیرد
--client-url	تنظیم‌نشده	مبدأ کلاینت وب میزبانی‌شده. یک پیوند عمیق قابل‌اسکن و یک QR ترمینال اضافه می‌کند

pair همچنین پرچم‌های هستهٔ --data-dir، --port و --bind را می‌پذیرد: آن‌ها پوشهٔ داده‌ای را که نوشته می‌شود تعیین و نشانی چاپ‌شدهٔ سرور را شکل می‌دهند (ws روی loopback، wss وقتی --bind any). اجرای دوبارهٔ pair برای همان --device کلیدش را می‌چرخاند و نشست‌های زندهٔ آن دستگاه را قطع می‌کند. اعتبارنامه‌ای که اینجا صادر می‌شود بدون انقضا است، برخلاف ۳۰ روزی که یک جفت‌سازی درون‌برنامه‌ای تعیین می‌کند.

QR مربوط به --client-url همان QR تلفن نیست

pair --client-url فرم اتصال کلاینت وب را پر می‌کند (نشانی سرور، شناسهٔ دستگاه و کلید در بخش fragment نشانی). تلفن با محتوای متفاوتی جفت می‌شود که از پنل جفت‌سازی درون‌برنامه صادر می‌شود — توصیف‌گر کامل اتصال سرور به‌همراه یک انقضا. این دو جانشین‌پذیر نیستند — جفت‌کردن دستگاه را ببینید.

update

--apply نصب را جایگزین می‌کند؛ تا وقتی سروری هنوز روی پورت پیکربندی‌شده پاسخ می‌دهد رد می‌شود، مگر اینکه --force را بدهید. --allow-downgrade یک نسخهٔ قدیمی‌تر را مجاز می‌کند.

این فرمان برای نصب‌هایی که مالکشان نیست، سرراست رد می‌کند — با یک توضیح، نه یک خطا:

محیط	شناسایی با	آنچه می‌گوید
سرور جاسیشدهٔ برنامهٔ رومیزی	CC_EMBEDDED=1 یا CC_BOOTSTRAP_DEVICE_ID	در عوض برنامه را به‌روزرسانی کنید — نصب‌کننده کل درخت را جابه‌جا می‌کند
یک checkout منبع dart run	مسیر اسکریپت به .dart ختم می‌شود	آن را با git به‌روزرسانی کنید
Docker	نشانگرهای کانتینر	یک ایمیج تازه‌تر را pull کنید

چرخهٔ عمر فرایند

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 که با این سرور ثبت می‌شود
• پشتیبان‌گیری و بازیابی — کپی‌کردن این پوشه به جایی امن
• پشتیبان‌گیری، برون‌بری و درون‌بری — چیدمان اسنپ‌شات و هر عملیات پشتیبان‌گیری
• اتصال به سرور راه دور — نشانه‌گرفتن یک کلاینت به یکی از آن‌ها
• استقرار و کلاینت‌ها — چرا سرور مالک همه‌چیز است