# CMai OS Belgeleri (tam metin)

Kaynak: https://docs.cmaios.com/ · Ürün: https://cmaios.com/ · ISO: https://releases.cmaios.net/ · Portal: https://portal.cmaios.com/ · İletişim: isgelistirme.ortaklik@cmapps.com.tr
İngilizcesi: https://docs.cmaios.com/en/llms-full.txt
Son güncelleme: 2026-08-28

CMai OS, AI geliştirme sunucuları için geliştirilen kendi Linux dağıtımımızdır: kendi çekirdek yapılandırması, Ed25519 ile imzalı güncelleme kanalı ve kendi ISO'suyla dağıtılır (Server Edition, yalnızca amd64). Dört AI kurulu gelir: CMai (CMai API — tek anahtar, tüm modeller) ile Claude Code, Gemini CLI ve Kimi CLI; her kullanıcı rootless podman ile izole edilmiş kendi çalışma alanında çalışır. Kurulumdan ilk `cmai` komutuna giden yol dört adımdır: 1) Kur — ISO'yu açın; katılımsız kurulum diskin tamamını alır. 2) Sihirbaz — konsol kartındaki adres ve kodla tarayıcıdan lisans + CMai API anahtarı + yönetici. 3) SSH — `ssh <yönetici>@<ip>` doğrudan çalışma alanına iner. 4) Yayınla — projeler sunucunun alan adında otomatik alt alan adı + TLS ile yayınlanır.

## Gereksinimler

| Bileşen | Başlangıç önerisi | Not |
|---|---|---|
| CPU | 8 vCPU | yalnızca amd64 (x86-64) |
| RAM | 32 GB | kullanıcı başına ayıracağınız kotaları toplayın |
| Disk | 500 GB NVMe | kurulum diskin tamamını alır |
| Ağ | sabit IP önerilir | lisans için giden HTTPS erişimi (license.cmaios.net) gerekir |
| Firmware | BIOS veya UEFI | ikisi de desteklenir |

Tek kullanıcılı bir deneme çok daha küçük bir makinede (ör. 2 vCPU / 4 GB sanal makine, 40 GB disk) çalışır; yukarıdaki değerler ekip kullanımı için başlangıç noktasıdır.

## ISO indirme

Güncel ISO https://releases.cmaios.net adresinde. Her sürümün yanında bir `.sha256` dosyası bulunur; indirdikten sonra doğrulayın:

    curl -LO https://releases.cmaios.net/cmaios-latest-amd64.iso
    sha256sum -c cmaios-<sürüm>-amd64.iso.sha256
    # cmaios-<sürüm>-amd64.iso: OK

Windows'ta `certutil -hashfile cmaios-<sürüm>-amd64.iso SHA256` çıktısını `.sha256` dosyasındaki değerle karşılaştırın.

## VirtualBox / bare-metal kurulum

DİKKAT: kurulum katılımsızdır ve seçili diskin TAMAMINI siler. Üzerinde veri olan bir makinede çalıştırmayın.

- VirtualBox: "Linux / Other Linux (64-bit)" tipinde bir makine oluşturun; en az 2 vCPU, 4 GB RAM, 40 GB disk verin. ISO'yu optik sürücüye takın. Ağ modunu Köprü (Bridged) yapın ki sunucu yerel ağınızdan bir IP alsın ve tarayıcıdan ulaşabilin. EFI açık ya da kapalı olabilir.
- Bare-metal: ISO'yu USB'ye yazın (dd, Rufus, balenaEtcher), makineyi USB'den başlatın. BIOS ve UEFI ikisi de desteklenir; Secure Boot açıksa firmware ayarlarından kapatın.
- Açılış menüsünde kurulum otomatik başlar, disk bölümlenir, paketler kopyalanır ve makine yeniden başlar. Müdahale gerekmez.

## İlk açılış ve sihirbaz

Kurulumdan sonraki ilk açılışta konsolda bir kart görürsünüz:

    Kurulumu tamamlamak için tarayıcıdan açın
      Adres          https://192.168.1.40:8443
      Kurulum kodu   Q63X-FE73
      Sertifika uyarısında "Gelişmiş → Devam et" seçin.
      Kurulum bitene kadar SSH ve diğer servisler kapalıdır.

1. Adresi açın. Panel kendi imzaladığı bir sertifika kullanır; tarayıcının uyarısında "Gelişmiş → Devam et" deyin.
2. Kurulum kodunu girin. Karttaki 8 haneli, tek kullanımlık kod (XXXX-XXXX). Konsola erişimi olmayan kimse sihirbazı açamaz.
3. Lisans anahtarı: `CMAI-XXXX-XXXX-XXXX-XXXX` biçimindeki anahtarınız. Sunucu lisans servisine bağlanır, anahtar bu cihaza bağlanır.
4. CMai API anahtarı: https://app.cmai.tr/customer/keys adresinden oluşturduğunuz `cm-…` anahtarı. Tek anahtar, her kullanıcının çalışma alanına işlenir (bkz. "CMai API ve AI araçları").
5. Yönetici hesabı: kullanıcı adı ile SSH açık anahtarı ya da parola. Anahtar önerilir; anahtar verirseniz o kullanıcı için parola girişi açılmaz.

Sihirbaz bittiğinde konsol kartı "CMai OS hazır" durumuna geçer; SSH satırını, panel adresini ve lisans özetini gösterir. SSH artık açıktır. Kurulum kodunu sonradan görmek için konsolda `cmai setup code`; kart silindiyse `cmai banner` yeniden çizer.

## Bağlanma

    $ ssh admin@192.168.1.40
    CMai OS hazır  ·  çalışma alanı: admin  ·  /workspace
    admin@cmai:/workspace $ cmai

Çalışma alanı kavramı: SSH ile giren her kullanıcı ana sisteme değil, kendi çalışma alanına iner — rootless podman ile çalışan, o kullanıcıya özel bir konteyner. İçinde CMai CLI (`cmai`), claude, gemini, kimi, derleyiciler ve git hazırdır. Ev dizini HOME=/workspace'tir ve kalıcıdır. CPU, RAM ve süreç sayısı kullanıcı başına kotalıdır (`cmai user add` ile belirlenir).

### CMai API ve AI araçları

CMai API — tek anahtar, tüm modeller. CMai (https://cmai.tr), CMApps tarafından geliştirilen kurumsal yapay zeka platformudur: sohbet, görsel, ses-video ve embedding tek standart API'de (OpenAI uyumlu Chat Completions); kredi yönetimi ve canlı izleme dahil. CMai OS'ta sihirbazın AI adımında girilen TEK CMai API anahtarı her kullanıcının çalışma alanına işlenir; çalışma alanında `cmai` (ya da `cmai code`) komutu bu API üzerinde çalışan, terminalde yaşayan CMai yapay zeka kodlama ajanı CMai CLI'ı başlatır (varsayılan model `cmai-pro`).

CMai CLI (@cmapps/cmai-cli) her çalışma alanında önceden kuruludur ve sunucunun anahtarıyla CMai API'ye otomatik bağlanır (CMAI_API_KEY / CMAI_MODEL / CMAI_BASE_URL). Otomatik hafıza, beceriler (skills), alt-ajanlar ve MCP desteği: `cmai -p "…"` tek seferlik komut çalıştırır, `cmai mcp add …` MCP sunucusu ekler, proje köküne konan `CMAI.md` kalıcı talimat verir. Ayarlar /workspace/.cmai altında kalıcıdır. Modeller: cmai-pro, cmai-balanced, cmai-fast, cmai-vision. Kendi makineye kurulum: `npm install -g https://cmai.tr/downloads/cmai-cli-latest.tgz`.

1. Anahtar alın: https://app.cmai.tr/customer/keys (anahtar `cm-…` ile başlar).
2. Girin: sihirbazın AI adımında; sonradan değiştirmek için yerel yönetici paneli https://<ip>:8443.
3. Kullanın: SSH ile girin, `cmai` yazın (`cmai code` da aynı şeyi yapar).

Çalışma alanında hazır ortam değişkenleri (OpenAI uyumlu her araç ek ayar olmadan CMai API'ye bağlanır):

| Değişken | Değer |
|---|---|
| CMAI_API_KEY | sihirbazda girilen cm-… anahtarı |
| CMAI_BASE_URL | https://gw.cmai.tr/v1 |
| CMAI_MODEL | cmai-pro (CMai CLI'ın varsayılan modeli; cmai-balanced, cmai-fast, cmai-vision seçilebilir) |
| OPENAI_API_KEY | CMAI_API_KEY ile aynı (OpenAI uyumlu araçlar için ayna) |
| OPENAI_BASE_URL | CMAI_BASE_URL ile aynı |

API uç noktaları: POST /v1/chat/completions (SSE ile akış, tool/function calling, metin · görsel · PDF · ses · video girdisi), /v1/embeddings, /v1/files, /v1/models. Kimlik doğrulama: `Authorization: Bearer cm-…`. Modeller (7): cmai-pro (varsayılan, 200K bağlam), cmai-balanced (200K), cmai-fast (128K), cmai-vision (1M), cmai-av (ses-video, 1M); embedding için cmai-embed-small ve cmai-embed-large (yüksek kaliteli, 8K). Tam referans: https://docs.cmai.tr/docs

    curl "$CMAI_BASE_URL/chat/completions" -H "Authorization: Bearer $CMAI_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"model":"cmai-fast","messages":[{"role":"user","content":"Merhaba"}]}'

Diğer AI araçları (kendi hesabınızla): Claude Code · Gemini CLI · Kimi CLI her çalışma alanında kuruludur ve `claude`, `gemini`, `kimi` ile başlar; ilk çalıştırmada kendi sağlayıcı hesabınız ya da API anahtarınızla oturum açarsınız (BYOK). Claude Code, Anthropic'in kendi API biçimini gerektirdiğinden CMai API üzerinden çalışmaz. CMai API kullanımı app.cmai.tr üzerindeki CMai kredilerinizden düşer; hiçbir AI kullanım ücreti CMai OS lisansına dahil değildir.

Host komutları: ana sistemdeki komutlar (yönetim CLI'ı cmai, systemctl, journalctl) çalışma alanının içinden görünmez. Yönetici bunları SSH'ın komut argümanıyla, sudo üzerinden çalıştırır:

    ssh admin@192.168.1.40 "sudo cmai license status"
    ssh admin@192.168.1.40 "sudo cmai user add ayse --cpus 2 --mem 4096 --ssh-key 'ssh-ed25519 AAAA…'"
    ssh admin@192.168.1.40 "sudo journalctl -u cmai-workspace-ayse -f"

Aynı komutlar sunucunun konsolundan doğrudan da verilebilir.

## CLI referansı

Yönetim CLI'ı `cmai` ana sistemde çalışır ve root gerektirir (sudo); çalışma alanındaki CMai CLI (`cmai`) ile karıştırmayın.

| Komut | Ne yapar |
|---|---|
| cmai license status | Lisans durumu: plan, kullanıcı sayısı, geçerlilik, bağlantı durumu, cihaz kimliği |
| cmai license activate <anahtar> | Anahtarı bu cihaza bağlar; kilitli sunucuyu açmanın konsol yolu |
| cmai license renew | Lisans servisiyle hemen eşitler |
| cmai license deactivate | Anahtarın bu cihazla bağını kaldırır; anahtar başka sunucuda kullanılabilir |
| cmai user add <ad> [--cpus N] [--mem MB] [--pids N] [--ssh-key "…"] [--password-stdin] [--no-start] | Yeni sandbox kullanıcısı; kota ve giriş yöntemiyle |
| cmai user start\|stop\|rm <ad> | Kullanıcının çalışma alanını başlatır, durdurur ya da kullanıcıyı siler |
| cmai user shell <ad> [komut…] | Kullanıcının çalışma alanında kabuk (ya da tek komut) açar |
| cmai update check | Seçili kanalda yeni sürüm var mı bakar |
| cmai update apply | Güncellemeyi uygular |
| cmai update channel [stable\|beta\|nightly] | Güncelleme kanalını gösterir / değiştirir |
| cmai doctor | Servisleri, ağı, lisansı ve çalışma alanlarını denetler |
| cmai banner | Konsol kartını yeniden çizer |
| cmai setup code | İlk açılış kurulum kodunu gösterir |

## Lisanslama

CMai OS çevrimiçi etkinleştirme kullanır: anahtar bir kez cihaza bağlanır, sunucu lisansını çevrimiçi doğrular.

| Olay | Davranış |
|---|---|
| Etkinleştirme | Sihirbazda ya da `cmai license activate` ile. Anahtar bu sunucunun cihaz kimliğine bağlanır |
| Bağlantı | Sunucunun license.cmaios.net adresine giden HTTPS erişimi olmalıdır. Kısa kesintiler çalışmayı etkilemez; bağlantı uzun süre kurulamazsa kilit modu, bağlantı gelince otomatik açılır |
| Kilit modu | SSH, çalışma alanları ve yayınlar durur. Veri silinmez. Konsol kartı nedeni ve panel adresini gösterir |
| Kilidi açma | Yerel yönetici paneli https://<ip>:8443 → yeni anahtar gir, ya da konsolda `cmai license activate <anahtar>`. Yeniden kurulum gerekmez |
| Sunucu değişimi | Eski sunucuda `cmai license deactivate` (ya da portal.cmaios.com'da "Cihazı serbest bırak"), yeni sunucuda aynı anahtarla etkinleştirme |

Planlar ve fiyatlar (aylık, USD, KDV hariç; AI kullanım ücretleri dahil değil): Trial ücretsiz (14 gün, 1 kullanıcı, 1 sunucu); Solo $29/ay (1 kullanıcı, 1 sunucu); Team $99/ay (5 kullanıcı dahil, ek kullanıcı $19/ay, en fazla 20 kullanıcı, 1 sunucu); Enterprise teklifle, sunucu başına $499/ay'dan başlayan (20+ kullanıcı, çoklu sunucu, öncelikli destek). Güncel liste: https://cmaios.com/#planlar. Anahtar ve teklif için isgelistirme.ortaklik@cmapps.com.tr. Müşteri portalı (https://portal.cmaios.com/): lisanslar, bağlı cihazlar, cihaz serbest bırakma, yenileme talebi; giriş parolasız, e-posta bağlantısıyla.

## Yönetim paneli

Sihirbazın çalıştığı adres kurulumdan sonra yönetici paneline dönüşür: https://<ip>:8443. Sihirbazda oluşturulan yönetici hesabıyla girilir. Lisans sayfasında: lisans durumu (etkin / kilitli / lisans yok), plan, kullanıcı sayısı ve geçerlilik; cihaz kimliği, bağlantı durumu ve lisans sunucusu adresi; "Yenile" (sunucuyla hemen eşitle); "Yeni lisans anahtarı / anahtarı değiştir"; "CMai API anahtarı" (değiştirme; tüm çalışma alanlarına işlenir, CMai CLI bununla çalışır); bağlantı özeti (SSH satırı, yönetici adı, sürüm). Panel yerel ağdan ya da sunucunun IP'sinden erişilecek şekilde tasarlanmıştır; sertifikası kendi imzalıdır.

## Güvenlik

CMai OS askeri düzey şifreleme standartlarıyla (AES-256 / Ed25519 / TLS 1.3) gelir; varsayılanlar sıkıdır ve tümü kutudan çıktığı gibi etkindir:

| Katman | Önlem |
|---|---|
| İmza | Lisans yanıtları ve güncelleme paketleri Ed25519 ile imzalı; imzası doğrulanmayan güncelleme uygulanmaz, lisans yanıtı kabul edilmez |
| Aktarım | Tüm trafik (lisans servisi, güncelleme kanalı, panel, yayınlanan projeler) TLS 1.2+/1.3 ile şifreli; düz HTTP yok |
| SSH | Anahtarlı erişim; SSH anahtarı girildiğinde ya da panelden eklendiğinde parola girişi otomatik kapanır; kurulum bitene kadar SSH kapalı |
| Güvenlik duvarı | nftables varsayılan-kapalı: yalnızca 22 (SSH), 8443 (panel), 80/443 (yayınlar) açık |
| Kaba kuvvet | fail2ban tekrarlanan SSH ve panel denemelerini engeller |
| İzolasyon | Her kullanıcı kendi rootless podman çalışma alanında: read-only rootfs, cap-drop ALL, no-new-privileges, CPU/RAM/disk/süreç kotaları |
| Anahtarlar | Lisans anahtarı, CMai API anahtarı ve cihaz kimliği yalnızca sunucuda, root-only dosyalarda; dışarıya kod ya da veri çıkmaz |

Tam disk şifreleme, FIPS sertifikasyonu ve donanım tabanlı anahtar saklama (TPM zorunluluğu) bu sürümde yoktur. Güvenlik bildirimleri: https://cmaios.com/.well-known/security.txt

## Sorun giderme

- SSH "Permission denied (publickey)": sunucu yalnızca anahtarla girişi kabul ediyor ve gönderilen anahtarı tanımıyor. Doğru anahtarı kullanın (`ssh -i ~/.ssh/id_ed25519 admin@<ip>`); sihirbazda parola seçtiyseniz `ssh -o PubkeyAuthentication=no admin@<ip>`; başka kullanıcı anahtarı için `sudo cmai user add <ad> --ssh-key "…"`.
- "Çalışma alanınız hazırlanıyor": ilk girişte konteyner oluşturulur; workspace imajı hazırlanıyorsa birkaç dakika sürebilir. İzleme: `ssh admin@<ip> "sudo journalctl -u cmai-workspace-<ad> -f"`. Takılırsa `sudo cmai user stop <ad>` ardından `sudo cmai user start <ad>`; genel sağlık için `sudo cmai doctor`.
- Konsol kartı IP göstermiyor: kart ağ arayüzü adres almadan çizilmiş olabilir; konsolda Enter'a basın. Hâlâ IP yoksa DHCP'yi ve sanal makinede ağ modunun Köprü olduğunu kontrol edin.
- Sistem kilitli: kart "Sistem kilitli — lisans geçerli değil" diyorsa nedeni de yazar (süre doldu, askıya alındı, lisans servisine ulaşılamıyor). Panelden ya da `cmai license activate` ile yeni anahtar girin; bağlantı sorunuysa `cmai license renew`.

## Sürümler ve güncelleme

Sürüm biçimi: `0.1.0-dev.<n>+<sha>` — n derleme sayacı, sha kaynak kodun kısa git özeti. Kurulu sürümü `cmai license status` çıktısında ve panelde görürsünüz; ISO'ların yanındaki `-BUILD.txt` dosyası derleme ayrıntılarını içerir. Güncellemeler `cmai update check` / `cmai update apply` ile yönetilir; kanal stable, beta ya da nightly olabilir. Paket tabanlı apt kanalı (apt.cmaios.net) yakında; o zamana kadar yeni sürümler releases.cmaios.net üzerinden ISO olarak yayınlanır.

## Sık sorulanlar

- Kurulum kodunu kaybettim: konsolda `cmai setup code`; kart silindiyse `cmai banner`.
- Lisans anahtarını sonradan değiştirmek: panelde "Yeni lisans anahtarı" ya da `sudo cmai license activate CMAI-…`; yeniden kurulum gerekmez.
- Sunucu kilitlendi, veri silindi mi? Hayır; kilit modunda servisler durur, disk olduğu gibi kalır.
- Aynı anahtar iki sunucuda? Lisansın sunucu sınırı kadar; sınır dolunca eski cihazı serbest bırakın.
- Kullanıcılar ana sisteme erişebilir mi? Hayır; herkes kendi rootless podman çalışma alanında, host komutları yalnız yöneticide sudo ile.
- CMai API anahtarı nereden? https://app.cmai.tr/customer/keys (cm-…); sihirbazın AI adımında girilir, sonradan https://<ip>:8443 panelinden değiştirilir; her çalışma alanına CMAI_API_KEY olarak işlenir.
- CMai CLI nedir? @cmapps/cmai-cli — terminalde yaşayan CMai yapay zeka kodlama ajanı; her çalışma alanında önceden kurulu, sunucunun CMai API anahtarıyla otomatik bağlanır. `cmai` (ya da `cmai code`) etkileşimli oturum, `cmai -p "…"` tek seferlik komut, `cmai mcp add …` MCP sunucusu, proje kökünde CMAI.md ile kalıcı talimat; otomatik hafıza, beceriler, alt-ajanlar; ayarlar /workspace/.cmai (kalıcı); modeller cmai-pro / balanced / fast / vision.
- AI kullanımı için ayrı ücret? Evet; CMai API kullanımı app.cmai.tr üzerindeki CMai kredilerinden düşer, Claude Code · Gemini CLI · Kimi CLI kendi sağlayıcı hesabıyla çalışır; hiçbiri lisansa dahil değildir.
- Portlar: dışarıdan 22 (SSH), uzaktan panel için 8443, yayınlar için 80/443; sunucudan license.cmaios.net'e giden HTTPS.
- Yedekleme: kullanıcı verisi /workspace altında; sunucu düzeyinde snapshot/rsync ya da kullanıcıların git ile uzak depoya göndermesi.

## Sözlük

- Çalışma alanı (workspace): kullanıcıya ait rootless podman konteyneri; SSH girişi buraya düşer; HOME=/workspace kalıcı.
- Kullanıcı sayısı: lisansın izin verdiği kullanıcı sayısı.
- Sunucu sınırı (max devices): aynı anahtarın aynı anda etkin olabileceği sunucu sayısı.
- Cihaz kimliği (device id): etkinleştirmede sunucudan türetilen benzersiz kimlik; varsa TPM ile güçlendirilir.
- Doğrulama: sunucunun lisansını license.cmaios.net üzerinden çevrimiçi doğrulaması.
- Kilit modu: lisans geçersizken SSH, çalışma alanları ve yayınların durduğu, verinin korunduğu durum.
- Kanal (channel): güncelleme akışı — stable, beta, nightly.
- Konsol kartı: fiziksel konsoldaki durum kartı (panel adresi, kurulum kodu, SSH satırı, lisans özeti).
- Kurulum kodu: sihirbazı açmak için tek kullanımlık 8 haneli kod (XXXX-XXXX).
- CMai API anahtarı: app.cmai.tr/customer/keys adresinden alınan cm-… anahtarı; sihirbazda bir kez girilir, her çalışma alanına CMAI_API_KEY olarak işlenir; CMai CLI (`cmai`) bununla çalışır.
- Anahtar ipucu (key hint): anahtarın son dört karakteri (CMAI-…-XXXX).