Remana Agent Cluster
TEKNİK SUNUMPLATFORM · GÜVENLİK · OPERASYON

Remana
Agent Cluster

Kodlama ajanlarını kendi makinelerinizde çalıştıran kontrol düzlemi. İşler kuyruğa girer, sandbox profiliyle çalışır, onaydan geçer ve her adım denetim kaydına yazılır.

KURULUMself-hosted · compose
WORKERWindows · macOS · Linux
BAĞLANTIgiden WSS · TLS 1.3
RUNTIMEClaude Code · Codex · Pi · OpenCode
←/→ · boşluk · PageUp/PageDown · M liste · G git · F tam ekran01 / 32
SORUN

Ajanlar gerçek makinelerde, çoğu zaman kimse bakmıyorken çalışıyor

BUGÜN
REMANA'DA MEKANİZMA
Ajan, okuduğu depo metnini talimat sanar. Bir README satırı ona git push --force yazdırabilir.
Ajan çıktısı ve depo içeriği yetki vermez. Push, merge, deploy ve sır okuma platform tabanında; proje politikası bunları gevşetemez.
Sağlayıcı anahtarları ve abonelik girişleri ajanın erişebildiği ortamda durur.
Kimlik bilgileri tarayıcıda her worker'ın anahtarına mühürlenir; master yalnız şifreli metin görür. Abonelik girişine platform hiç dokunmaz.
Makine meşgulse ikinci iş düşer. Onay bekleyen iş slotu saatlerce tutar.
Geçici ret işi kuyrukta tutar. 60 dakika bekleyen onay işi duraklatır, slotu boşaltır, aynı makinede devam ettirir.
Hangi komut çalıştı, kim onayladı, sonradan kanıtlanamaz.
Her geçiş Postgres'te tek işlemle yazılır; denetim kaydı SHA-256 ile zincirlenir.
Panel deploy'u, reboot ya da worker yeniden başlaması saatlerdir süren işi öldürür. Birden çok ajan, birbiriyle çakışan ayrı PR'lar bırakır.
Master 15 dk gitse de iş sürer; worker yeniden başlarsa iş checkpoint'ten aynı denemede devam eder. Ajanların dalları tek dalda birleşir, tek PR olur.
Ajan "bitti" der, sonuç doğrulanmadan yayına çıkar.
Doğrulama kapısı yayını alıkoyar; yayından sonra sağlık kontrolü ve isteğe bağlı geri alma.
kaynak: docs/security/threat-model.md (T-INJ, T-SBX), ADR-0039, ADR-0041, ADR-004202 / 32
REMANA NEDİR

Tek kontrol düzlemi, makinelerde ajanlar

Master işleri sıraya koyar, politika ve onaylardan geçirir, kendi makinelerinizdeki worker'lara dağıtır. Worker ajanı seçilen sandbox profilinde çalıştırır ve sonucu geri yollar.

  • Master sizin işlettiğiniz bir host'ta docker compose ile çalışır: API, zamanlayıcı, Postgres, Redis, backup servisi. Veri ve sırlar kendi altyapınızda kalır.
  • Worker Windows, macOS ve Linux'ta işletim sistemi servisidir; master'a yalnız giden WSS bağlantısı açar. Makinede dinleyen port açılmaz.
  • Runtime olarak Claude Code, Codex, Pi ve OpenCode. Sürümler pinli; runtime politikası canary'den stable'a yükseltir.
  • Çıktılar master'da toplanır: dosyalar, siteler (Cloudflare Pages, Coolify), önizleme tünelleri.
animasyon · 14 sn · mimari
kaynak: ARCHITECTURE.md, docs/ops/cicd.md, docs/ops/worker-install.md03 / 32
BİLEŞENLER

Beş parça, her birinin tek bir işi var

kendi host'unuz · docker compose

Master

Fastify API; her route'ta yetki kontrolü, varsayılan ret. Zamanlayıcı ve yerleştirme. Postgres doğruluk kaynağı: her durum geçişi bir outbox satırıyla aynı işlemde yazılır.

Redis / BullMQ yalnız teslim ipucu taşır (jobId, attemptId, fencingEpoch). Redis kaybolursa durum Postgres'ten uzlaştırılır.

Kasa yalnız şifreli metin tutar. Denetim kaydı append-only ve hash zincirli.

tarayıcı · PWA

Web konsol

Chat, Jobs, Outputs, Uptime, Machines, Usage, Audit. Katı CSP: script-src 'self', inline script yok. Telefona uygulama olarak kurulur, Web Push alır.

Windows · macOS · Linux servisi

Worker daemon

Windows 10/11'de NT SERVICE\RemanaWorker, macOS'ta (Apple silicon, Intel) LaunchDaemon, Linux'ta (x64, arm64, Raspberry Pi OS) systemd. Ed25519 cihaz anahtarı. Kesintide sonuçları fsync'li outbox'ta tamponlar; çalışan işlerin checkpoint'ini alır, yeniden başlayınca aynı denemeyi sürdürür.

worker içinde adaptör

Runtime adaptörleri

Claude Code (Agent SDK), Codex (app-server), Pi (RPC), OpenCode (loopback sunucu). Yetenekler doğru bildirilir; desteklenmeyen özellik varmış gibi sunulmaz.

compose içinde

Backup servisi

Gece yedeği, owner anahtarlarına şifreli kurtarma sırları, S3/R2 kopyası, isteğe bağlı WAL arşivi ile yedek panel (RPO ≤ 5 dk), haftalık geri yükleme tatbikatı.

kaynak: ADR-0003, ADR-0008, ADR-0016, docs/design/p10-backup-restore.md, ADR-0039, ADR-004204 / 32
PROTOKOL VE KİMLİK

Worker'ın kimliği bir anahtar, işi imzalı bir lease

  • Tek giden WSS (TLS 1.3) wss://<master>/v1/worker. NAT ve kurumsal güvenlik duvarı arkasında çalışır; VPN ya da gelen port gerekmez.
  • Eşleştirme: 10 dakikalık tek kullanımlık kod ve Ed25519 parmak izi; admin step-up ile onaylar.
  • Oturum: her bağlantıda sunucu nonce'u cihaz anahtarıyla imzalanır; en çok 15 dakikalık oturum tokeni. Uzun ömürlü bearer sır yok. İptal canlı soketi hemen kapatır.
  • Lease: master'ın Ed25519 ile imzaladığı kısa ömürlü token ve iş başına artan fencing epoch. Eski epoch'lu her yazma reddedilir ve denetlenir. Master'a ulaşılamazsa lease 15 dk çevrimdışı toleransla sürer.
  • Sürümleme: Zod şemalı zarf, MAJOR.MINOR; bilinmeyen alanlar atılır, master mevcut ve önceki major'ı birlikte konuşur.
// worker → master · her mesaj
{
  "protocolVersion": "1.0",
  "type": "EVENT",
  "messageId": "…",      // tekrar → yeniden işlenmez
  "workerId": "…",
  "jobId": "…",
  "seq": 1842,            // monoton
  "ts": "…",
  "correlationId": "…",
  "payload": { "epoch": 3, … } // eski epoch → ret
}
Teslim en az bir kez. Tüketiciler idempotent; git dalı rac/<jobId>/<attempt> ve commit trailer'ı denemeyi taşır, eski bir deneme yenisinin üstüne yazamaz.
kaynak: ADR-0003, ADR-0004, ADR-0005, ADR-0011, ADR-003905 / 32
İŞ YAŞAM DÖNGÜSÜ

Taslaktan hafızaya, her adım ayrı bir kapı

animasyon · 19 sn · iş yaşam döngüsü
DRAFT→QUEUED→RESERVED→STARTING→RUNNING→VERIFYING→AWAITING_APPROVAL→SUCCEEDED
PAUSEDRETRY_WAITLOSTBLOCKEDCANCELLEDFAILED
  • Geçişler açık bir geçiş tablosuna göre doğrulanır; geçersiz geçiş reddedilir ve denetlenir.
  • Master'a 15 dakikaya kadar ulaşılamazsa iş sürer; worker yeniden başlarsa checkpoint'ten devam eder. Bunlar da olmazsa iş körlemesine yeniden çalışmaz: LOST olur ve uzlaştırılır, yalnız güvenle tekrarlanabilen iş otomatik yeniden denenir.
  • PAUSED: deneme açık, lease yok, slot boş. Üç sebep: onay bekleme, kullanım limiti, worker yeniden başlaması. Devam aynı denemede, epoch + 1.
kaynak: ADR-0004, ADR-0036, ADR-0039, ADR-0040, ADR-0042, docs/design/p4-job-state-machine.md06 / 32
CHAT · OPS ASİSTANI · İŞ YÖNETİMİ

Asistan taslak hazırlar, işleri de yönetir; onaylayan insandır

  • Asistan sunucuda değil, seçilen bir worker'da Claude Code ile çalışır; kabuğu, dosya ve web erişimi yok. Panel araçları kullanıcının kendi yetkisiyle çalışır, master model anahtarı tutmaz.
  • find_jobs kastedilen işi çözer (id öneki, başlık sözcükleri, durum grubu, "son başarısız iş"). Tek işlik istekte birden çok aday varsa sorar, tahmin etmez.
  • draft_job_action: cancel, run_again, continue, set_class, move, run_now; kartta en çok 50 iş, iş başına işaret kaldırılabilir. Confirm authenticator kodu ister.
  • Onayda master her işi onaylayan kişi için yeniden okur (görünürlük, izin, durum) ve Jobs ekranının çağırdığı servisin aynısını çalıştırır. Sonuç iş başına done / skipped / refused / failed; bayat iş hata değil, açık bir satır.
  • Acil yalnız run_now ile (admin + step-up) ve kullanıcının kendi sözüyle. Her eylem iş başına chat.job_action olarak denetlenir; "haber ver" izlemeleri ve Web Push kişiye özel.
gerçek panelüst: chat ana ekranıalt: kartın şematik çizimi · örnek veri
kaynak: ADR-0018, docs/design/p10-chat-job-actions.md, docs/canvas/chat.md07 / 32
İŞLER VE KUYRUK

Meşgul makine işi düşürmez, bekletir

  • Sınıflar: Acil +50 · Normal 0 · Arka plan −50. Dağıtım sınıf sırasıyla; sınıf içinde yaşlanma (her 60 sn +1) ve projeler arası ağırlıklı adil pay. Yaşlanma sınıfı değiştirmez.
  • Acil rezervi: makine başına 0/1/2 slot (varsayılan 1), en az iki paralel slot varsa uygulanır.
  • Geçici ret (declineKind: transient) işi kuyrukta tutar. Yalnız kalıcı ret o makineyi iş için dışlar.
  • Profil başına slot: worker her profil için kapasitesini bildirir; master ret beklemeden bekletir ve sebebini gösterir.
  • Abonelik girişleri giriş deposu başına tek tek çalışır; API anahtarlı işler paralel. Sohbetten gelen iş Normal'dir; Acil'i yalnız kullanıcının kendi mesajı yaptırır.
animasyon · 17 sn · kavramsal örnek
kaynak: ADR-0033, docs/canvas/kuyruk-plani.md08 / 32
MAKİNELER VE KAPASİTE

Kapasite tahminle değil, ölçümle

  • Öneri ölçülen değerlerden çıkar. Örnek kart (4 CPU, 7.9 GB RAM'li bir Windows makinesi): Recommended: 1 parallel job — Claude Code peaks ~2.8 GB, o makinedeki 12 işin ölçümüyle.
  • Panel yapılandırması öneriden fazla isterse liste ve makine sayfası uyarır (above recommended 1). Kapasite modu: manuel, öneri ya da sınırlar içinde otomatik.
  • Worker yapılandırması panelden yönetilir: imzalı, nesil numaralı, hash'li. Makinedeki yerel tavan panelden geleni her zaman sınırlar.
  • Liste: durum, yük, slotlar (3 slots (unconfined: 1), 1 kept for Acil), hazır runtime'lar.
gerçek panelWindows x64 worker · makine adı maskelendi
kaynak: ADR-0015, docs/design/p8-capacity-auto.md09 / 32
KULLANIM LİMİTLERİ · GÖRÜNÜRLÜK VE FALLBACK

Limit önceden görünür, dolunca iş düşmez

  • Okuma: worker yalnız runtime'ın sunduğunu okur. Claude Code 5 saatlik, haftalık ve model bazlı haftalık pencereler; Codex planın 5 saatlik ve haftalık penceresi. Kaynak: iş olay akışı ve 10 dakikada bir modele istek atmayan salt-okunur sorgu. Kimlik bilgisi dosyası okunmaz.
  • Görünürlük: composer'da runtime seçicinin altında tek satır, chat iş kartı, makine sayfasında "Runtime limits", listede rozet, Home özeti, Usage → Enforcement. %80'i geçen pencere için owner ve admin'e dönem başına tek bildirim.
  • Dolunca: adaptör hatayı usage_limited olarak sınıflar; giriş sorunu ve geçici 5xx limit sayılmaz. İş PAUSED olur, slot boşalır; worktree, sandbox klasörü ve oturum saklanır. Reset gelince aynı deneme, aynı makine, epoch + 1.
  • Maliyet güvenliği: API anahtarlı fallback ancak allowPaidFallback ile; bütçeler fallback'te de geçerli. Bildirim iş başına değil limit başına: başlarken bir, açılınca bir.
  • Okumalar bilgi amaçlıdır: zamanlayıcı yalnız gerçek limit dolmalarına göre davranır. API anahtarı hız limitleri ancak dolunca görünür; runtime'lar sağlayıcı başlıklarını vermez.
örnek veri · şematik çizimpolitika: auto · wait · fallback · fail
kaynak: ADR-0040, ADR-0046, docs/design/p11-usage-limit-fallback.md, docs/design/p11-limit-visibility.md10 / 32
RUNTIME ÖNERİSİ

Hangi işe hangi runtime: geçmiş sonuçtan öneri, seçim insanda

  • Sınıflandırma kurallı, LLM yok: iş türü + alan (frontend, backend, tests, docs, infra). İşaretler ağırlıklı: açık JobSpec.area, sonucun dokunduğu yollar (önce projenin glob kuralları), alt işin paths'i, prompttaki dosya adları, Türkçe ve İngilizce anahtar sözcükler. Net fark yoksa "sınıflandırılmamış".
  • Deneme değil sonuç: iyi sonuç = başarılı ve doğrulamada ya da CI'da düşmedi, merge'de reddedilmedi, birkaç gün içinde (varsayılan 3) aynı promptla tekrar çalıştırılmadı, olumsuz oy almadı.
  • İstatistik: proje × alan × runtime (× model); yarı ömürlü ağırlık (varsayılan 60 gün), filonun oranına merkezli Beta önsel, ~%95 aralık, en az 5 iş.
  • Öneri varsayılandır (composer, chat kartı, koordinatörün alt iş isteği): kanıtıyla gösterilir, işi değiştirmez.
  • Otomatik mod proje bazında opt-in (admin + step-up), yalnız runtime'ı "auto" olan işlere. İzinli runtime'lar, ücretli politika, açık limitler ve makine durumu içinde seçer; %10 keşif (en çok %30), production deploy işlerinde hiç. Açıkça seçilen runtime asla değiştirilmez; karar ve gerekçesi işe yazılır.
örnek veri · şematik çizimmod: off · advice (varsayılan) · auto
kaynak: ADR-0044, docs/design/p11-runtime-advice.md, docs/canvas/runtime-onerisi.md11 / 32
SANDBOX PROFİLLERİ

Her işletim sistemine kendi kafesi, zayıfa düşüş yok

PROFİLNEREDEİZOLASYON
containerLinux, rootless Docker/Podmansalt-okunur kök, düşürülmüş yetenekler, seccomp, egress allowlist proxy
runtime-sandboxCodex (Linux, Windows), Claude Code (Linux)runtime'ın kendi sandbox'ı + host kısıtları
host-restrictedWindows, macOS, Linux/Pi hostözel düşük yetkili hesap; Windows Job Object, macOS Seatbelt
unconfinedyalnız izin verilen makine + projedosya/ağ sınırı yok; kaynak limitleri ve kimlik kuralı sürer
  • Politika bir profil isterse ve worker veremiyorsa iş reddedilir; daha zayıf profile kendiliğinden geçilmez.
  • Prepare panelden imzalı bir komuttur; SYSTEM/root yardımcısı imzayı kendisi doğrular ve yalnız imzalı pakete gömülü sabit adımları çalıştırır.
  • unconfined için makine anahtarı, proje opt-in'i ve taze TOTP gerekir; makine sahibi yerel config ile tamamen yasaklayabilir.
gerçek panelPrepare succeeded · runtime-sandbox, host-restricted, unconfined ready
kaynak: ADR-0007, ADR-0019, docs/canvas/sandbox.md12 / 32
WINDOWS · İŞ BAŞINA HESAP

Paralel host işleri, birbirinin klasörünü göremeden

  • Her eşzamanlı host denemesi kendi yerel hesabında çalışır: remana-job-1…N (havuz 1–16, varsayılan max(maxParallelJobs, 4)).
  • Hesaplar yalnız batch logon alır; interaktif, RDP, ağ ve servis girişi kapalı, oturum ekranında gizli. Rastgele parolalar yalnız DPAPI LocalMachine blob olarak saklanır.
  • Runner hesabı LOGON32_LOGON_BATCH ile açar, runtime'ı CreateProcessAsUser ile worker'ın Job Object'i içinde başlatır.
  • Deneme klasörlerine korumalı DACL. İş bitince izinler geri alınır; temizlik başarısızsa hesap karantinaya girer.
  • Paralellik ancak makinede çapraz erişim öz-testi geçince açılır. Abonelik girişli işler bu hesaplara verilmez: paylaşılan OAuth yenilemesi paralel çalışmada girişi bozduğu için tek tek çalışırlar.
Panel kartı: Parallel: up to 3 for API-key runtimes; subscription logins run one at a time (each API-key attempt runs as its own Windows account)
Kalan ortak yüzey: localhost portları, süreç listesi, egress proxy (Windows'ta işletim sistemi zorlamaz). macOS host denemeleri Seatbelt ile ayrışır ve paralel; Linux/Pi host profilleri şimdilik tek tek.
kaynak: ADR-0034 (ekler 1–2), threat model T-SBX-413 / 32
ONAYLAR VE GÜVENLİ KOMUTLAR

Zararsız komut beklemez, çünkü iki taraf ayrı ayrı kanıtlar

  • Platform tabanı projeden gevşetilemez: korumalı dala push ve merge, force push, deploy, workspace dışı silme, sır okuma, bütçe artışı.
  • Worker runtime'ın çalıştıracağı komutu ayrıştırır, yolları diskte çözer (symlink, hard link, .git) ve bir iddia ekler.
  • Master komutu kendisi yeniden sınıflandırır. Kararlar eşitse onaylar ve approval.auto_safe denetim kaydı yazar; değilse istek insana gider.
  • Ayrıştırıcı regex değil: bash/sh/zsh, PowerShell ve cmd için dar alt kümeler. Değişken, glob, script bloğu, bilinmeyen alias: hepsi sorulur.
  • Full access (unconfined + "Never ask") proje opt-in'i, makine izni ve güvenilir kaynak ister; her anahtar taze TOTP, denetim ve sahiplere bildirimdir.
gerçek panelSafe commands · varsayılan: Read-only commands
kaynak: ADR-0010, ADR-0020, docs/design/p6-safe-auto-approve.md14 / 32
OKUNABİLİR ONAY KARTLARI

Onaylayan, neyi onayladığını okuyabilir

  • Önce: istek araç: JSON metni olarak 2 KiB'de kesiliyordu; tırnaklar kaçışlı, ajanın kendi açıklaması blob'un içinde kayboluyordu.
  • Yapılandırılmış alanlar (protokol 1.0'a isteğe bağlı details): araç, ajanın açıklaması (Claude Code ve OpenCode description, Codex reason), tam komut (16 KiB, satır sonları korunur), shell, çalışma klasörü, yollar, URL. Önce ayrıştırılır, sonra kesilir: yarım JSON komut diye gösterilmez.
  • Kart sırası: ajanın sözü "unverified" etiketiyle → komut, birebir çalışacağı haliyle (Copy orijinali kopyalar; Formatted yalnız okuma içindir) → alanlar → "What this touches" → ham metin kapalı bölmede.
  • What this touches deterministik bir statik okumadır, LLM yok: Runs, Reaches, Writes, Deletes, Installs, Reads env vars, Outside the workspace, Rights. "Garanti değil" diye etiketli; hiçbir şeye karar vermez, politika ve risk aynen kalır.
  • Güvenlik: yalnız düz metin olarak çizilir; bidi ve sıfır genişlikli karakterler görünür yapılır (Trojan Source). Sır değerleri worker'da kesmeden önce, master'da saklamadan önce maskelenir. Bildirimde ≤ 160 karakterlik etiketli tek satır.
şematik çizim · örnek komut$b önceki atamadan çözülür → chrome.exe
kaynak: ADR-0010, docs/design/p10-approval-readable.md15 / 32
ONAY BEKLEME · PAUSE / RESUME

Onay bekleyen iş düşmez: duraklar, sonra kaldığı yerden sürer

  • Çalışma içi istek süresi dolup işi düşürmez. 15 dk sonra stale: hatırlatma bildirimi, sohbete bir not.
  • 60 dk sonra fenced PAUSE_JOB: runtime nazikçe durur, lease bırakılır, slot boşalır. Workspace, sandbox klasörü ve oturum 7 güne kadar saklanır.
  • Karar gelince aynı deneme, aynı makine, epoch + 1. Öncesinde politika, onaylayanın rolü ve makine yeniden kontrol edilir.
  • Karar eylemin parmak izine bağlıdır (eylem + özet için sha256). Ajan başka bir komut isterse yine insana sorulur.
  • Devam edemeyen iş başka makineye taşınmaz; konsol Restart from scratch ya da Cancel önerir. Duraklama süresi iş süresinden düşmez.
gerçek panelüst: 26 dk duraklama → devam → Succeeded · alt: workspace kayıp, Restart/Cancel bekliyor
kaynak: ADR-0036, docs/canvas/onay-bekleme.md16 / 32
ORKESTRASYON · ALT İŞLER

Ajan işin bir parçasını başka bir runtime'a devreder

  • Ajan request_subtask, wait_subtask, cancel_subtask araçlarını kullanır; dört runtime'da da var. Her çağrı canlı lease'e fenced bir SUBTASK_REQUEST olur.
  • Alt iş sıradan bir iştir: aynı kuyruk, kota, bütçe, onay ve denetim. İkinci bir zamanlayıcı yok.
  • Spec ajandan değil ana işin kayıtlı spec'inden türetilir. Sandbox ve kaynak güveni aynı, onay politikası aynı ya da daha sıkı; sır, deploy ve fallback aktarılmaz; bütçe ana işten kesilir.
  • Sınırlar: derinlik ≤ 2, iş başına ≤ 8 (aynı anda ≤ 4), aile başına ≤ 16. Proje başına varsayılan kapalı; açmak taze TOTP ister.
  • Abonelik girişli Claude ana iş ile Codex alt işi ayrı giriş depolarındadır; aile istisnasıyla aynı makinede birlikte çalışır. Alt işlerin dalları master'ın birleştirme hattında tek PR'a toplanır.
Üretimde gözlendi: Claude koordinatör ve Codex alt işi aynı anda çalıştı; Codex görseli üretip teslim etti. Ekrandaki deneme makineyle bağlantı kopunca needs human review ile durdu: lease'i kaybolan iş körlemesine yeniden çalıştırılmaz.
kaynak: ADR-0031, ADR-0034 ek 2, ADR-0041, ADR-0045, docs/canvas/orkestrasyon.md17 / 32
BİRLEŞTİRME HATTI

Birden çok ajanın işi tek dalda toplanır, tek PR olur

  • Master yönetir: alt işler ve koordinatör bitince int/<root8> hedefin güncel head'inden açılır. Birleştirmeyi ajansız bir entegrasyon işi yapar: worker'da gerçek git, hook yok, attributes boş ağaçtan. Böyle işi yalnız master açabilir.
  • Sıra: bağımlılıklar → çakışmayan kardeşler → örtüşenler. Alt iş istekleri paths taşır; örtüşme ajana ve konsola uyarılır.
  • Doğrulanmadan sayılmaz: her adımın dalı uzak depoda doğrulanır; entegrasyon head'ine dayandığı ve bildirilen commit'leri içerdiği kontrol edilir. int/ yalnız fast-forward; dışarıdan oynanmış dal insana gider.
  • Çakışma: tur durur; sınırlı bir çözüm işi iki tarafın diff'ini, işaretleri ve iki görev tanımını veri olarak alır, yalnız çakışan dosyaları yeniden yazar. Varsayılan en çok 3 tur, sonra insan.
  • Tek PR: projenin testleri birleşik dalda çalışır (kırılırsa 1 düzeltme işi). Üyelerin kendi PR'ı olmaz; açıklamada görevler, runtime'lar, çakışma kaydı, test sonucu. Merge insan onayıyla: admin + taze kod.
Alt iş araçları dört runtime'da: Claude Code süreç içi MCP, Codex app-server dinamik araçları, Pi eklenti rölesi. OpenCode yerel stdio MCP sunucusu ve deneme klasöründe dosya rölesiyle: soket yok, port yok, sandbox profili değişmedi.
şematik · örnek dal adlarıher kutu sıradan bir iş: kuyruk, kota, bütçe, denetim
kaynak: ADR-0041, ADR-0045, docs/design/p11-merge-pipeline.md, docs/canvas/birlestirme.md18 / 32
OTURUM SÜREKLİLİĞİ

Worker yeniden başlasa da iş aynı denemede sürer

  • Checkpoint: varsayılan 2 dakikada bir, yalnız değişiklik varsa ve boyut sınırı içinde. Gizli ref refs/remana/checkpoints/<attempt>/<n> üzerine worker'ın kendi index'iyle WIP commit: iş dalına girmez, push edilmez. Oturum işaretçisi ve son araç çağrıları fsync'li kayıtta; master'a yalnız metadata.
  • Yeniden başlayınca, ilk heartbeat'ten önce: dizinler yerinde mi, eski çalıştırmadan süreç ya da container kaldı mı (kimlik kontrollü; emin değilse devam etmez), güvenilen git metadata'sı ve son checkpoint sağlam mı.
  • Master LOST uzlaştırmasından önce park eder (sebep worker_restart) ve aynı denemeyi aynı worker'da epoch + 1 ile sürdürür. Eski epoch bir daha çalışmaz; deneme başına en çok 2 yeniden başlama.
  • Yarım kalan araç çağrısı körlemesine tekrarlanmaz. Dış etkili ya da bilinmeyen çağrı için ajana "sonucu bilinmiyor, tekrar denemeden önce doğrula" denir; onaylar yeniden sorulur.
  • Native resume yalnız canlı doğrulanmış runtime sürümlerinde. Diğerlerinde yeni oturum checkpoint'ten devam istemiyle başlar: görev, transcript sonu, son çağrılar, diff, TODO'lar.
RUNNING · e3→checkpoint 1…7→worker yeniden başladı→PAUSED · worker_restart→RUNNING · e4 · checkpoint 7'den→SUCCEEDED
ARAÇ ÇAĞRISI SINIFIÖRNEKYENİDEN BAŞLAMADA
idempotentdosya okuma, git statusyeniden çalıştırılabilir
workspace_writedosya düzenleme, buildcheckpoint'ten geri gelir
externalgit push, deploy, paket kurulumu"unknown outcome — verify before retrying"
unknownsınıflanamayanexternal gibi; onay yeniden sorulur
Gerçek bir Windows worker'da doğrulandı: çalışan işin worker servisi yeniden başlatıldı; iş kısa süre PAUSED oldu, aynı denemede checkpoint'ten sürüp tek deneme olarak tamamlandı.
kaos testi: işin ortasında worker sürecine SIGKILL → yeniden başlar, iş bir kez tamamlanır
kaynak: ADR-0042, ADR-0004, ADR-0036, docs/design/p11-session-continuity.md19 / 32
ÇIKTILAR VE ÖNİZLEME TÜNELLERİ

Ne üretildiyse tek yerde, ne açıldıysa tek porttan

  • Outputs: canlı siteler, out/ dosyaları, notlar. Önizleme (Markdown, CSV, JSON, PDF, diff), SHA-256, saklama süresi, pin, klasörler, 100 dosya / 50 MiB ZIP ve MANIFEST.txt.
  • Site HTML'i script çalışmayan sandbox'lı çerçevede gösterilir; secret taramasının işaretlediği paket hiç gösterilmez.
  • Önizleme tüneli: master her önizleme için tek ingress kurallı bir Cloudflare Tunnel kurar. Worker'a yalnız o tünelin connector token'ı gider: 0600 dosyada, komut satırında değil.
  • Yalnız işin kendi süreç ağacının dinlediği port açılır; SSH, RDP, veritabanı ve worker'ın kendi portları reddedilir. Varsayılan 4 saat, en çok 24 saat; tahmin edilemez hostname.
gerçek panelOutputs · Cluster test / General / Machines klasörleri
kaynak: ADR-0032, docs/canvas/ciktilar.md, docs/canvas/onizleme-tunelleri.md20 / 32
DOĞRULAMA · DEPLOY · UPTIME

Yayın onayı iş açılırken verilir, kapı sonucu görene kadar bekler

  • Deploy on success: onay iş oluşturulurken alınır (politikaya göre taze TOTP). Tek kullanımlık, 8 gün geçerli kayıt; tekrar çalıştırma devralmaz. Production proje bazında ayrıca açılır.
  • Verify when done: off · report · gate. Master sitenin linklerini kendisi kontrol eder; doğrulayıcı iş build/test çalıştırır, Playwright ile 1280×800 ve 390×844 ekran görüntüsü, konsol hataları, kırık linkler.
  • Kapı yalnız alıkoyar: doğrulayıcının "geçti" demesi yetki vermez. Override proje admini ve taze kod ister, denetlenir.
  • Deploy sonrası sağlık: SSRF korumalı prob ve aynı-köken tarama; isteğe bağlı otomatik geri alma (production için ikinci anahtar).
  • Uptime: HTTP/TCP, Cloudflare Pages, Coolify. Metadata adresi, localhost, özel ağlar reddedilir; her yönlendirme yeniden kontrol edilir.
gerçek panelCloudflare Pages + HTTP monitörü · 24 sa / 7 g / 30 g
Doğrulayıcı ve deploy sonrası sağlık kontrolü entegrasyon testleriyle kapsanıyor; gerçek Pages/Coolify deploy'larıyla saha doğrulaması yol haritasında.
kaynak: ADR-0028, ADR-0030, ADR-0035, docs/canvas/uptime.md21 / 32
TEK ONAYLI YAYIN ZİNCİRİ

Alan adında yayın: dört adım, tek onay

1 · PAGES PROJESİYoksa oluştur

Yalnız hesapta yeni bir ad; projenin hedefi değişmez, ek Pages projesi olarak listelenir.

pages.create_project
2 · DEPLOYİş sonucu ya da yüklenen site

Preview ya da production. Plan anahtarı dosya hash'lerini içerir; dosyalar değişirse adım durur.

pages.deploy
3 · ALAN ADICustom domain bağla

Yalnız projenin hedefi ya da yönetici listesindeki Pages projesi; başka ad 403.

pages.add_domain
4 · DNSCNAME yaz

İzinli zone'da, projenin kendi pages.dev adına. Korumalı kayıtlar reddedilir.

dns.upsert
onay bir kez, taze kodla→ dört bağlı eylem, her biri "Approved with its publish bundle" gerekçesiyle ayrı denetlenir
  • pages.publish tek ops eylemidir: bütün olarak planlanır (tek diff, adım başına karar) ve en sıkı adımına göre karar verilir. Production ya da DNS yazımı varsa onay + her seferinde taze kod.
  • Onaydan sonra her adım ayrı bir ops eylemi olarak çalışır ve ayrı denetlenir. Her adımdan önce onaylayan ve isteyen yeniden yetkilendirilir, adım yeniden planlanır; gerçekler değiştiyse durur. Başarısız adım zinciri keser.
  • DNS "Run at once" yalnız projenin kendi Pages adına giden CNAME'ler için; silme onay + step-up ister. Production her zaman en az bir onay ister.
  • Ajan isteyebilir: chat taslağı (insan onaylar) ya da işin kendi ajanı publish_site ile. Yalnız insanın açtığı, güvenilir kaynaklı işlerde; iş başarılı bitince tek bir pages.publish.
  • Site yükleme: klasör ya da tarayıcıda açılan .zip, 4 MiB'lık sürdürülebilir parçalar. En çok 500 dosya, dosya başına 25 MiB, toplam 50 MiB; mp4 ve webm dahil. SHA-256, magic byte ve metin dosyalarında secret taraması.
  • Master arşiv açmaz; konsol yüklenen HTML'i asla sunmaz, yalnız metadata döner. Token'lar master'da kalır.
kaynak: ADR-0028, ADR-0037, ADR-0038, docs/design/p10-publish-bundle.md, docs/design/p10-site-upload.md22 / 32
HAFIZA · BEDROCK

İnsan onaylar, bilgi birikir, sohbet anlamca bulur

animasyon · 14 sn · hafıza ve anlamsal arama
  • Biten işlerin özetleri ve projeye bağlı sohbetler kurallarla okunur (MEMORY:, KARAR:, paket yöneticisi, marka rengi…). Operator kabul etmeden hiçbir şey context'e girmez; kabul edilen öneri tipli bir kayıt olur.
  • Embedding: AWS Bedrock cohere.embed-multilingual-v3, 1024 boyut. Anahtar panelden girilir, master'da şifreli durur, worker'a gitmez.
  • Gönderilen yalnız izinli projelerin doküman, iş özeti ve sohbet metni. Prompt, log, araç çıktısı ve sırlar gönderilmez.
  • Her mesajda en çok 6 parça (~6 KB), kullanıcının okuyabildiği kaynaklardan, "veri, talimat değil" bloğunda. Başkasının özel sohbeti hiç kullanılmaz. Bedrock yoksa aynı akış anahtar sözcükle çalışır, dışarı bir şey gitmez.
kaynak: docs/design/p10-semantic-memory.md, docs/canvas/proje-hafizasi.md23 / 32
HAFIZA · KATMANLAR

Kural, bilgi, karar, ders: her birinin kapsamı ve ömrü var

  • Tipli kayıt: rule, fact, decision (karar, bağlam, sonuçlar, tarih, kim), lesson. Kapsam: global, runtime, kişisel (user:<id>), proje, proje + runtime. Sürüm, yazma rolleri, secret taraması, denetim ve iş başına pinleme mevcut bağlam deposundan.
  • Yaşam döngüsü: işe ve aramaya yalnız active ve süresi dolmamış kayıt girer. Supersede, expire ve reject açık insan eylemidir; review-by tarihi bildirim üretir. Çelişki yalnız öneridir: "bu, X'in yerini alabilir".
  • Dört runtime'a aynı paket: master tek bir render üretir; Claude Code, Codex, Pi ve OpenCode bunu birebir ilk mesajda alır. İş, aldığı sürümleri saklar.
  • Ajan deneyimi önerilir, yazılmaz: cevaptaki LESSON: ve MEMORY: satırları öneri kutusuna düşer; operator türünü ve kapsamını seçip kabul eder.
  • Kişisel kurallar yalnız sahibinin açtığı işlere ve sohbetlerine gider; admin dahil kimse göremez.
  1. Platform politikasıdeğiştirilemez
  2. Global kurallarasla kesilmez
  3. İşi oluşturanın kişisel kurallarıasla kesilmez
  4. Proje kurallarıasla kesilmez
  5. Kararlar64 KiB bütçe · 1. öncelik
  6. Bilgiler2. öncelik
  7. Dersler (runtime'a özel olanlar yalnız o runtime'da)3. öncelik
gerçek panelöneri kutusu · tür içinde önce alaka (Bedrock), sonra yenilik
kaynak: ADR-0043, docs/design/p11-memory-layers.md, docs/canvas/hafiza-katmanlari.md24 / 32
KULLANIM VE MALİYET

Harcanan para ile tahmin ayrı satırda

  • API harcaması gerçek dolardır. Abonelik kullanımı token, tur ve saat olarak gösterilir; yanında "API-equivalent ≈ $X (estimate)". Bilinmeyen maliyet sıfır sayılmaz, "≥" alt sınır olarak yazılır.
  • Kırılım: proje, runtime, model, makine, otomasyon; en pahalı ve en yavaş işler; CSV.
  • Bütçeler gün/hafta/ay, saat dilimiyle. %50/%80/%100 eşikleri. %100'de: yalnız uyar, yeni işleri beklet ya da yalnız otomasyonları durdur. Override sebep ve TOTP ister.
  • API-equivalent tahmin, Usage → Prices'a girilen sürümlü fiyat tablosundan hesaplanır; fiyat yoksa "unknown — price missing" yazar.
  • Öneriler sabit kurallarla ve kanıtıyla gelir; hiçbiri kendiliğinden uygulanmaz. Haftalık rapor her Pazartesi 08:00, kişinin saat diliminde.
örnek veri · gösterim amaçlıtahmin örnek fiyatlarla: Claude $3 / $15, Codex $1.25 / $10 (1M girdi / çıktı token)
kaynak: ADR-0014 §5, docs/canvas/maliyet-verimlilik.md25 / 32
GÜVENLİK MODELİ

Ajan çekirdekte, her halka ayrı bir kapı

animasyon · 14 sn · güvenlik katmanları
  • İnsan: scrypt parola + zorunlu TOTP. Oturum çerezi HttpOnly, Secure, SameSite=Strict; CSRF çift gönderim. Step-up penceresi 10 dk; hesap güvenliği işlemleri her seferinde taze kod.
  • Roller: owner, admin global; operator, viewer proje bazında. Başka projenin kaynağı 404 döner.
  • Güvenilmeyen içerik: depo metni ve ajan çıktısı hiçbir şeyi yetkilendirmez. Fork PR'lar unconfined, auto-approve ve deploy alamaz.
  • Denetim: append-only, SHA-256 hash zinciri, aralık doğrulama; dışa aktarım step-up ister.
kaynak: ADR-0009, ADR-0010, docs/design/p5-rbac.md, docs/design/p5-search-audit.md26 / 32
SIRLAR VE KİMLİK BİLGİLERİ

Master anahtarları taşır ama açamaz

1 · TARAYICIAdmin değeri girer

Değer her seçili worker'ın X25519 anahtarına ayrı ayrı mühürlenir: HKDF-SHA256 + AES-256-GCM, yalnız WebCrypto.

açık metin yalnız burada
2 · MASTERYalnız şifreli metin

Metadata ve worker başına şifreli metin saklar; hiçbir route değeri kabul etmez, döndürmez, loglamaz. Yazma: admin + taze step-up + CSRF.

açamaz
3 · İLETİMİmzalı APPLY_CREDENTIAL

Lease anahtarıyla imzalı; worker, kimlik bilgisi, sürüm ve şifreli metin özetine bağlı. Eski ya da çelişen sürüm reddedilir.

şifreli
4 · WORKERAçar, kendi deposuna yazar

Kendi anahtarıyla açar, yerel sır deposuna koyar, yalnız id + sürüm bildirir. İş başına ortam değişkeni olarak enjekte edilir.

açık metin yalnız burada
  • Vault anahtarı worker'ın Ed25519 cihaz anahtarıyla imzalanıp duyurulur; master eşleştirmede pinlediği anahtarla doğrular. Anahtar değişirse kayda geçer ve bildirilir.
  • Yazma-yalnız: döndürülür, kaldırılır, iptal edilir; asla geri gösterilmez.
  • Abonelik girişi (Claude, ChatGPT): platform okumaz, kopyalamaz, iletmez. Tarayıcı ve worker sk-ant-oat… token'larını reddeder; durum yalnız authenticated: yes | no | unknown.
  • Master'ın tuttuğu entegrasyon sırları AES-256-GCM ile, HKDF alt anahtarlarıyla saklanır; worker'a ve sohbet asistanına gitmez. Log redaksiyonu hem worker'da hem master'da.
kaynak: ADR-0006, ADR-0014, ADR-0016, ADR-002827 / 32
KESİNTİ TOLERANSI

Kontrol düzlemi 15 dakika gitse de çalışan iş ölmez

  • Önce: lease 90 sn; master'a ulaşamayan iş yaklaşık 3 dakikada kendini durduruyordu. Bir deploy, reboot ya da kısa ağ kesintisi çalışan işleri düşürüyordu.
  • Çevrimdışı tolerans: offline-grace-v1 worker'lara her lease ile 15 dk (LEASE_OFFLINE_GRACE_MS), lease başına değişmez şekilde saklanır. Master lease'i bitişinden sonra tolerans + bir lease ömrü boyunca tutar: canlı sayılır, slot korunur, LOST yapılmaz; master yeniden başlasa da.
  • Güvenli saat: worker toleransı onaylanan LEASE_ACK'in gönderilme anından sayar, yenilemenin varışından değil; mesaj gecikmesi güvenlik hesabına girmez. Master ulaşılabilir ama yenilemeyi reddederse worker hemen durur.
  • Tampon: sonuçlar, olaylar, loglar ve onay istekleri fsync'li outbox'ta bekler; dönüşte saniyede en çok 150 mesajla uygulanır. Outbox dolarsa runtime yavaşlatılır, iş düşürülmez.
  • 15 dakikadan uzunsa worker kendini durdurur, iş LOST olur; yalnız güvenle tekrarlanabiliyorsa yeniden denenir. Kesinti boyunca iptal ve onay kararları işe ulaşamaz.
Kaos testleri: master 10 dk kapalı → iş sürer, tek çalışma, tek commit. 20 dk → durur, LOST, güvenli yeniden deneme. Master yeniden başlarken worker çevrimdışı ve standby'dan geri yükleme sonrası yeniden bağlanma da kapsanır; tolerans kapalı negatif kontrol düşer.
kaynak: ADR-0039, ADR-0004, docs/design/p11-master-resilience.md, docs/ops/slo.md28 / 32
YEDEKLEME · YEDEK PANEL

Yedek, geri yüklenene kadar yedek sayılmaz

  • Her gece 02:30 UTC tutarlı dump; manifest: şema sürümü, satır sayıları, SHA-256, denetim zinciri başı. Kurtarma sırları age ile owner anahtarlarına şifreli; sunucuda açacak anahtar yok.
  • Saklama 7 günlük, 4 haftalık, 3 aylık. Haftalık tatbikat ağsız, geçici bir Postgres'e geri yükler, her şeyi yeniden kontrol eder ve WAL'ı yakın bir ana kadar oynatır.
  • Yedek panel: PG_WAL_ARCHIVE=on ile her WAL parçası age ile şifrelenip ~30 sn içinde S3/R2 bucket'ınıza gider (yalnız oluşturma izni); günde bir fiziksel taban yedek. RPO ≤ 5 dk.
  • standby-restore.mjs boş bir host'ta taban + WAL'ı çözüp istenen ana kadar kurar (anahtar yalnız owner'da); şema, satırlar, sırlar ve lease anahtarı kimliğini doğrular, DNS kaydını taşır. Hedef RTO ≤ 1 sa.
gerçek paneltatbikat PASSED · bütünlük, şema, migration, satırlar
Settings → Backups → Standby: son gönderilen WAL, gecikme, son taban yedek, son standby tatbikatı. Worker'lar geri kurulan panele aynı adresten kendiliğinden bağlanır. Sunucu dışı kopya yoksa panel uyarır; RPO o zaman 24 saate kadar çıkar.
kaynak: ADR-0039, docs/design/p10-backup-restore.md, docs/ops/backup-restore.md29 / 32
OPERASYON

Her sürüm imzalı, her deploy kapılı

  • Master deploy tek komut: image'lar host'ta build edilir, image ID'leri Ed25519 imzalı bir release kaydına yazılır ve rollout'tan hemen önce yeniden doğrulanır.
  • Deploy öncesi yedek, ileri yönlü migration, ardından sağlık kapısı. Uygulama deploy'u Postgres ve Redis'i yeniden yaratmaz.
  • Worker sürümleri çevrimdışı release anahtarıyla imzalanır; worker ve root güncelleyici imzayı ayrı ayrı doğrular. Geçiş atomik, başarısızsa geri döner; sürüm düşürme reddedilir.
  • Kanallar stable ve canary, yüzdeyle rollout: önce canary, sonra stable %10–25, sonra %100. Yükleme step-up ister ve denetlenir.
  • Önce master, sonra worker: yeni davranışlar worker özellik bayraklarıyla açılır (offline-grace-v1, session-continuity-v1, integration-v1, runtime-usage-v1). Eski worker eski davranışla çalışmaya devam eder.
  • Kaos testleri: master 10 / 20 dk kapalı, işin ortasında worker'a SIGKILL, standby'dan geri yükleme sonrası yeniden bağlanma. Değişmez kural: aynı deneme aynı epoch'ta iki kez çalışmaz.
ADIMMASTER DEPLOY · NE OLUR
preflighttemiz ağaç, commit'ten sürüm etiketi, imza anahtarı kontrolü
ship · buildgit archive (yalnız izlenen dosyalar, sır yok) → host'ta docker build
imzaimage ID'leri → imzalı release kaydı; rollout öncesi yeniden doğrulama
yedek · migratedeploy öncesi yedek, ardından ileri yönlü migration
sağlık kapısı~60 sn: container'lar healthy, imzalı image ID'leri çalışıyor, smoke istekleri geçiyor
keep · prunekapı geçmezse ve şema değişmediyse önceki sürüme otomatik dönüş; son sağlıklı sürümler tutulur, gerisi temizlenir
Şema ilerlediyse otomatik geri dönüş yapılmaz, çünkü eski master yeni şemayı reddeder: ileri düzeltme ya da deploy öncesi yedekten geri yükleme. Staging'de çalışan image ID'leri production'a aynen terfi eder.
kaynak: docs/ops/cicd.md, docs/ops/worker-updates.md, ADR-0011, ADR-0039, ADR-004230 / 32
OLGUNLUK VE YOL HARİTASI

Neler üretimde kanıtlı, neler yolda

ÜRETİMDE KANITLI · GERÇEK WINDOWS WORKER

  • Onay → stale → pause (slot boşalır) → onay → aynı makinede devam → Succeeded.
  • Worker yeniden başlatma: iş PAUSED (worker_restart) → aynı denemede checkpoint'ten devam → tamamlandı.
  • Katmanlı hafıza: tipli kayıtlar işin ilk mesajına enjekte edildi; işe verilen sürümler iş sayfasında görünür.
  • Kullanım pencereleri: Claude Code ve Codex'in 5 saatlik ve haftalık pencereleri composer, makine ve Home'da.
  • WAL arşivi: parçalar şifreli olarak sunucu dışı bucket'a gidiyor; tatbikat WAL oynatmasıyla geçti.
  • Windows iş başına hesaplar ile paralel host işleri; Claude ve Codex alt işleri eşzamanlı.
  • Bedrock anlamsal hafıza, gece yedeği ve haftalık tatbikat, imzalı sürüm hattı, uptime monitörleri.

YOLDA / BİLİNEN SINIRLAR

  • Çok işletim sistemli filo: macOS ve Linux worker'lar otomatik uçtan uca filo testinde; sahada en olgun hâli Windows.
  • Sandbox kaçış test setleri (Windows, Linux) yazılıyor. Linux/Pi host profilleri şimdilik tek tek çalışır.
  • Native resume: Claude Code ve Codex'in kendi oturumunu sürdürmesi canlı doğrulama bekliyor; o zamana dek checkpoint'ten devam istemi.
  • Gerçek Coolify deploy ve geri alma sahada doğrulanıyor; doğrulayıcı ve sağlık kontrolü bugün testlerle kapsanıyor.
  • Mobil push gerçek cihazda saha testi bekliyor.
  • 15 dk master kesintisinin canlı tatbikatı, boş bir host'a standby geri yükleme; birleştirme hattı ve limit fallback'inin gerçek depolarla ve gerçek limit mesajlarıyla saha denemesi.
  • Diyalog: sohbetin uygulamanın kendisi olduğu yeni arayüz bayrak arkasında yapılıyor; eski ekranlar bozulmadan.
kaynak: ADR'lerin "UNVERIFIED" notları, docs/ops/local-fleet-test.md, docs/canvas/diyalog-tasarim.md31 / 32
ÖZET

Ajanları başıboş bırakmadan,
kendi makinelerinizde çalıştırın.

KONTROL

Kuyruk sınıfları, profil başına slot, görünür limitler. Meşgul ya da limitteki makine işi düşürmez, bekletir.

KAFES

İşletim sistemine göre sandbox, Windows'ta iş başına hesap, iki taraflı kanıtla güvenli komut.

KANIT

İmzalı lease ve sürümler, hash zincirli denetim, tek PR'da birleşen iş, her hafta geri yüklenen yedek.

Kontrol düzlemi kendi host'unuzda docker compose ile; worker'lar Windows, macOS ve Linux makinelerinizde.

Remana Agent Cluster · Ekim 202632 / 32