Bölüm 24: Geliştirici Araçları ve Dev CLI¶

Sayfanın Amacı¶

Geliştirici Araçları sayfası, IDE ve terminal AI araçlarını Arceris üzerinden yönlendirmenin resmi yoludur. İki adres üzerinde çalışır:

Admin modu — /admin/developer-tools: kurulum rehberi ve kayıtlı cihazların agent sürümü dağıtımını yöneten Agent Güncelleme Dağıtımı paneli.
Kullanıcı modu — /developer-tools: yalnızca kurulum rehberi. Kullanıcı kendi cihazını buradan kaydeder; dağıtım paneli görmez.

Sayfa bir production özelliğidir — her planda görünür (feature: null).

İki Bileşen: Helper ve Makine Servisi¶

Arceris'in uç noktadaki varlığı v1.3.1'de iki katmanlıdır:

Bileşen	Kapsam	Görev
`arceris-dev` (helper)	Kullanıcı başına	Kayıt (enroll), kimlik yenileme, araç hook'ları, per-user proxy daemon'u
`arceris-agent` (servis)	Makine geneli (yalnızca Windows)	LocalSystem olarak çalışır; kimse oturum açmadan check-in eder, PAC'i sunar ve her kullanıcının helper'ını başlatır/yönetir

Servis katmanı MSI paketi ile kurulur. Kerberos'un olduğu ortamlarda hem makine hem kullanıcı kaydı sessizce gerçekleşir; Kerberos'un olmadığı ortamlarda kurulum token'ı akımı kullanılır (bkz. aşağıda Adım 1).

Setup — 3 Adımlı Kurulum¶

Adım 1 — CLI İndirme:

Sayfadaki işletim sistemi sekmelerinden (macOS / Linux / Windows) kullanılan platform seçilir; Arceris sunucusunda yayınlanmış derlemeler sayfada indirme kartları olarak listelenir. İndirme, kart üzerindeki bağlantıdan yapılır. Ziyaret edilen makinenin platform/mimarisine uyan derleme Önerilen rozetiyle işaretlenir ve listenin başında yer alır; her kartta dosya boyutu, mimari (amd64 / arm64) ve kopyalanabilir SHA-256 özeti görünür.

Windows servisi bloğu (yalnızca admin modu): Windows sekmesinde makine kapsamlı arceris-agent derlemeleri ayrı bir blokta listelenir. Makine kaydının yolu, ortamın Kerberos yapılandırmasına göre ikiye ayrılır:

Domain'e katılmış makine (Kerberos var): MSI paketi çift tıklanarak bile kurulabilir — makine AD bilgisayar hesabıyla kaydolur ve kullanıcı helper'ı da oturum açıldığında sessizce kaydolur; kullanıcının bir şey yapması gerekmez. Toplu dağıtımda aynı paket SCCM / GPO ile dağıtılır.
Kerberos yok (domain dışı makine): Kayıt üç adımda tamamlanır:
Makineler sayfasındaki "Kurulum token'ları" bölümünden tek kullanımlık, süreli (1–720 saat) bir kurulum token'ı üretilir — token yalnızca bir kez gösterilir, hemen kopyalanmalıdır.
MSI, token ile kurulur:

msiexec /i arceris-agent-windows-amd64.msi INSTALLTOKEN=<kurulum-tokenı>

Kullanıcı kaydı (helper), MSI'nın kurduğu araçla tamamlanır — sunucu adresi kurumunuza göre değişir:

& "C:\Program Files\Arceris\arceris-dev.exe" setup --server https://<arceris-sunucunuz> --no-browser --yes

Adım 2 — Tek Komutla Kurulum (setup):

v1.3.1'de onboarding tek komutta toplanmıştır. Kerberos'lu ve MSI ile yönetilen Windows makinelerinde bu adım gerekmez — kayıt sessizce yapılır (yukarıya bakın):

arceris-dev setup --server https://<arceris-sunucunuz>

Komut sırayla: (1) CA'yı çeker ve kayıt yapar — tarayıcı device-flow ile veya Kerberos/SPNEGO ile, (2) CA'yı işletim sistemi güven deposuna kurar, (3) arka plan daemon servisini kurar (OS düzeyi PAC dahil), (4) AI araçlarına hook takar (ör. Claude Code). setup admin parolasını bir kez ister (CA kurulumu için); bitince yönlendirmenin etkili olması için yeni bir terminal açılır. Her adım --no-* bayraklarıyla tek tek atlanabilir.

Sık kullanılan bayraklar:

Bayrak	İşlev
`--ca-file <path>`	CA'yı dosyadan ver (self-signed kurulumlar için)
`--insecure`	TLS doğrulamasını atla (yalnızca bootstrap; production'da SAN/CA tercih edin)
`--no-browser`	Tarayıcı yerine terminalde kullanıcı adı/parola sorar (GUI'siz makineler)
`--kerberos` / `--spn <spn>`	SPNEGO/Kerberos ile sıfır-dokunuş kayıt (domain'e katılmış uç noktalar; SPN `--server`'dan türetilir)
`--pin sha256/…`	Sunucu sertifikasının SPKI pin'i (GPO ile dağıtılır; `--insecure` ihtiyacını ortadan kaldırır)
`--proxy-port <n>`	Explicit proxy portu (varsayılan 3128)
`--no-system-proxy`, `--no-ca-install`, `--no-daemon`, `--no-integrate`, `--no-configure-shell`	İlgili adımı atla
`--yes`	Etkileşimsiz çalıştır: tüm sorularda varsayılanı kabul et

Self-signed / iç-CA sunucularda: makine sunucu sertifikasına henüz güvenmiyorsa CA HTTPS üzerinden otomatik çekilemez. Sayfadaki "CA sertifikasını indir (arceris-ca.crt)" bağlantısı (/api/auth/device/ca) CA'yı indirir ve kurulum şu şekilde yapılır:

arceris-dev setup --server https://<arceris-sunucunuz> --ca-file ~/Downloads/arceris-ca.crt

Bu akışta TLS doğrulaması baştan sona açık kalır; --insecure gerekmez.

Adım 3 — VS Code / Cursor Bağlantısı:

Eklenti mağazasından Arceris AI Gateway uzantısı kurulur ve proxy yönlendirmesi etkinleştirilir. Uzantı kaydı otomatik algılar — yapıştırılacak API anahtarı yoktur. Manuel yapılandırma gerekiyorsa VS Code settings.json dosyasına şu satır eklenir:

"arceris.proxyEnabled": true

Agent Güncelleme Dağıtımı (Yalnızca Admin Modu)¶

Admin modundaki Agent güncelleme dağıtımı paneli (/admin/api/agent-updates), kayıtlı cihazların hangi arceris-dev (helper) ve arceris-agent (servis) sürümüne güncelleneceğini platform/mimari bazında onaylamanızı sağlar. Cihazlar güncellemeyi bir sonraki check-in'de alır — ajanlar kendi kendilerine rastgele sürüme geçmez.

Panelin bölümleri:

a) Dağıtım kartları: Her ürün + platform/mimari çifti için bir kart. Kart, onaylanabilir derlemeleri listeler; bir derleme ve sürüm etiketi seçilip Onayla dendiğinde hedef sabitlenir (SHA-256 özeti manifest'ten alınır, elle girilmez). Kart başında dağıtım durumu rozeti görünür:

Tamamlandı — filonun tamamı onaylı sürümü raporluyor
Dağıtılıyor — hedef duyuruldu, cihazlar henüz geçiş aşamasında
Sürüm uyuşmazlığı — onaydan sonra check-in yapan hiçbir cihaz hedef sürümü raporlamıyor; etiket binary'nin bildirdiği sürümle uyuşmuyor olabilir
Onay güncel değil — onaylanan dosya diskte değişti/silindi (aşağıya bakın)
Hedef yok / Cihaz yok / Filo bilinmiyor

b) Onay güncelleme (Onay güncel değil): Onay bir dosyanın baytlarını sabitler. Gateway yükseltmesi indirme dizinini yeniden oluşturur; bu yüzden her gateway sürümü yükseltmesinden sonra agent derlemeleri yeniden onaylanmalıdır. Dosya onaydan sonra imzalanmış ya da elle kopyalanmışsa da aynı durum ortaya çıkar — güncelleme o ara hiçbir cihaza teklif edilmez.

c) İmza durumu: Her derleme imzalı / imzasız / okunamayan imza olarak etiketlenir. İmzasız bir derlemeyi imzasız bir filo kurar (ve update_unsigned bildirimi gönderir); imzalı makineler imzasız derlemeyi reddeder (unsigned_after_signed). Zaman damgası olmadan imzalanan derlemeler için sertifika süre-sonu uyarısı gösterilir.

d) Güvenilen kod imzalama anahtarları: İmzalı bir filo yalnızca çalışan derlemenin imzacısıyla imzalanmış güncellemeleri kurar. Yeni bir kod imzalama sertifikasına/CA'ya geçmeden önce yeni anahtar buraya eklenir — kaynak, yayınlanmış imzalı bir derleme ya da yapıştırılan PEM sertifika olabilir. İmzalama anahtarı (leaf) tek sertifikaya, CA anahtarı o CA'nın vereceği her sertifikaya güvenir; tüm CA değişikliği yoksa leaf tercih edilir.

e) Filo güncelleme matrisi: Her cihaz ve makine için "mevcut sürüm → onaylı hedef", güncellemenin ulaştığı aşama (Duyuruldu → İndirildi → Doğrulandı → Değiştirildi → Çalışıyor; servis katmanında "Servis güncelliyor"), takıldığı aşama ve son hata. Ürün/aşama/yalnız-takılanlar filtreleri vardır; matris ilk 2000 satırı gösterir.

f) Ajan etkinliği akışı: Filo çapındaki son 25 olay — swap tamamlandı/kanıtlandı, geri alındı, smoke testi başarısız, indirme/staging başarısız, sürüm etiketi uyuşmazlığı ve check-in kanalı olayları (checkin_failed / checkin_recovered).

Panelde ayrıca platform/mimari bildirmeyen cihaz sayısı ("bu cihazlara güncelleme hiç ulaşamaz") ve filo özeti ("N cihazın X tanesi onaylı sürümü raporluyor") görünür.

Çalıştığını Nasıl Anlarım? (Verify)¶

Kurulum sonrası üç doğrulama kartı sunulur:

Terminalde — arceris-dev doctor ile kayıt, daemon ve araç yönlendirmesini tek bakışta doğrulayan sağlık kontrolü.
VS Code'da — Durum çubuğunda Arceris ✓ görünür; ayrıntı için Arceris: Show Diagnostics komutu çalıştırılır.
Arceris'te — İstekleriniz Denetim Kayıtları'nda ve Kullanım Analizinde hesabınıza atfedilmiş olarak görünür.

Desteklenen Araçlar¶

Aşağıdaki IDE'ler ve araçlar resmi olarak desteklenir:

Cursor
VS Code
GitHub Copilot
Claude Code
Gemini CLI
Aider

Standart HTTPS_PROXY ortam değişkenini dikkate alan her araç, daemon kurulduğunda ek entegrasyon gerektirmeden çalışır.

CLI Komut Referansı¶

arceris-dev tüm komut listesini arceris-dev help ile, tek bir komutun ayrıntısını arceris-dev help <komut> ile basar:

Komut	Açıklama
`setup --server <url>`	Tek komutla onboarding: enroll + CA + daemon + araç entegrasyonu (bkz. Adım 2).
`uninstall`	Tam sökme — hook'lar, daemon, PAC, CA, kimlik bilgileri (`setup`'ın tersi). Çıkış kodu 0=tamamen temiz, 1=hata/iptal, 3=tamamlandı ama kalıntı var.
`enroll --server <url>`	Cihazı tarayıcı device-flow ile kaydeder; proxy + yenileme token'larını saklar. (`setup` bunu da kapsar; tek başına nadiren gerekir.)
`run`	Bir AI aracını proxy kimlik bilgileri hazır şekilde başlatır.
`daemon install` / `daemon uninstall`	Per-user arka plan servisini kurar/kaldırır. `install --server <url>` Kerberos otomatik-kaydı için sunucu adresini saklar; `--system-proxy` OS düzeyi PAC'i yapılandırır.
`integrate`	AI araçlarına yönetilen hook'ları kurar (ör. Claude Code MCP yakalama).
`ca install-system` / `ca uninstall-system` / `ca refresh`	Arceris kök CA'yı sistem güven deposuna kurar / kaldırır / yeniler.
`doctor`	Kayıt, CA ve araç yönlendirmesini doğrulayan sağlık kontrolü.
`status`	Kayıt durumunu ve broker sağlığını gösterir.
`daemon-info`	Daemon + kayıt durumunu JSON olarak basar (IDE eklentisi kullanır).
`token`	Geçerli proxy kimlik bilgilerini JSON olarak basar (IDE eklentisi kullanır).
`recipes`	Desteklenen araçları ve proxy/CA ortam değişkenlerini listeler.
`logout`	Sunucu kimlik bilgilerini iptal eder ve yerel kaydı kaldırır.
`help`, `version`	Komut yardımı ve sürüm bilgisi.

İlgili ortam değişkenleri: ARCERIS_PROXY (explicit proxy adresini geçersiz kılar, host:port) ve XDG_CONFIG_HOME (yapılandırma dizini; Linux/macOS varsayılanı ~/.config).

Arceris'i makineden tamamen kaldırmak için tek komut yeterlidir: arceris-dev uninstall.

Kullanıcı Modu Farkları¶

Kullanıcı modu (/developer-tools) aynı kurulum rehberini gösterir; Agent Güncelleme Dağıtımı paneli yalnızca admin modundadır. Binary'ler yayınlanmamışsa kullanıcıya "yöneticinizden bunları kullanılabilir kılmasını isteyin" bilgisi gösterilir.

Cihaz görüntüleme ve self-revoke bu sayfada değildir: kullanıcı kendi proxy token'ını profil sayfasından iptal eder, cihaz yönetimi ise admin tarafında Bölüm 13: Kayıtlı Cihazlar ve Dev CLI Cihaz Yönetimi'nde ele alınır.

Operasyonel Bağlam¶

Bu sayfa kurulumun nasıl yapılacağını anlatır; kayıt olan cihazların izlenmesi ve iptali Bölüm 13'te ele alınır. Bu sayfanın görünür olması lisans paketine bağlı değildir; tüm planlarda açıktır.