Codex harness’ını kullanmak: OpenAI App Server’ı nasıl kurdu

• Codex’in kendi ürününüze entegre edilebilmesi için standartlaştırılmış bir App Server mimarisi ve JSON-RPC protokolü oluşturulup sunuldu
• Başlangıçta CLI merkezli bir TUI harness’ından yola çıkıldı; ancak JSON-RPC protokolü benimsenerek IDE, web ve yerel uygulamalar gibi farklı istemcilerin aynı ajan döngüsünü paylaşabilmesi sağlandı
• App Server, Codex çekirdek kütüphanesini barındıran uzun süre çalışan bir süreçtir ve thread yaşam döngüsü yönetimi, yapılandırma/kimlik doğrulama, araç çalıştırma gibi tüm ajan deneyimini istemcilere sunar
• Item, turn ve thread olmak üzere üç konuşma primitive’i üzerinden ajan döngüsündeki karmaşık etkileşimler yapılandırılabilir ve zengin arayüzler oluşturulabilir
• VS Code, JetBrains, Xcode, masaüstü uygulaması ve web runtime gibi çeşitli yüzeylerde aynı harness yeniden kullanılır; Go, Python, TypeScript, Swift ve Kotlin dahil çok dilli istemci binding desteği sunulur
• MCP sunucusu, CLI modu ve TypeScript SDK gibi alternatif entegrasyon yolları da sağlanır; ancak App Server birincil entegrasyon standardı haline gelmiştir
• OpenAI, App Server’ı Codex entegrasyonu için varsayılan yol olarak sürdürürken, açık kaynak CLI deposu üzerinden herkesin Codex’i kendi iş akışına entegre etmesini destekliyor

---

App Server’ın temel arka planı

• Başlangıçta farklı ürünlerde Codex harness’ını yeniden kullanmak için pratik bir yöntemdi, ancak zamanla bir standart protokole dönüştü
• Codex CLI, bir TUI (terminal kullanıcı arayüzü) olarak başladı; VS Code uzantısı geliştirilirken aynı harness’ın IDE arayüzünde nasıl çalıştırılacağına ihtiyaç duyuldu
  • Workspace gezintisi, akıl yürütme ilerlemesinin akış halinde iletilmesi ve diff çıktısı gibi, istek/yanıtın ötesine geçen çeşitli etkileşim kalıplarının desteklenmesi gerekiyordu
• İlk aşamada Codex’i bir MCP sunucusu olarak açığa çıkarma denemesi yapıldı, ancak MCP semantiğini VS Code’a uygun biçimde korumak zordu
• Alternatif olarak TUI döngüsünü yansıtan bir JSON-RPC protokolü benimsendi ve bu, App Server’ın ilk gayriresmî sürümü oldu
  • O dönemde başka istemcilerin buna bağımlı olacağı öngörülmediği için kararlı bir API olarak tasarlanmamıştı
• Codex kullanımının yaygınlaşmasıyla birlikte iç ekipler ve dış ortaklar (JetBrains, Xcode vb.), harness’ı kendi ürünlerine gömebilme yeteneği talep etti
  • Geriye dönük uyumluluğu koruyarak protokolü geliştirebilecek bir platform yüzeyi tasarlama ihtiyacı doğdu

Codex harness’ının iç yapısı

• Codex Core, tüm ajan kodunu içeren bir kütüphane olmasının yanı sıra ajan döngüsünü çalıştıran ve tek bir Codex thread’inin (konuşmanın) sürekliliğini yöneten bir runtime’dır
• Temel ajan döngüsünün yanında üç ana işlev alanı bulunur:
  • Thread yaşam döngüsü ve kalıcılık: thread oluşturma, sürdürme, fork etme ve arşivleme; olay kaydını koruyarak istemcilerin yeniden bağlanıp tutarlı bir zaman çizelgesi render etmesini sağlar
  • Yapılandırma ve kimlik doğrulama: yapılandırma yükleme, varsayılanları yönetme, kimlik bilgisi durumunu izleme ve "ChatGPT ile giriş yap" gibi kimlik doğrulama akışlarını yürütme
  • Araç çalıştırma ve genişletme: sandbox içinde shell/dosya araçlarını çalıştırma; MCP sunucuları ve skill gibi entegrasyonları bağlayarak bunların tutarlı bir politika modeli altında ajan döngüsüne katılmasını sağlama

App Server mimarisi

• App Server, istemci ile sunucu arasında kullanılan bir JSON-RPC protokolü ve Codex Core thread’lerini barındıran uzun ömürlü bir süreçtir
• Dört ana bileşenden oluşur:
  • stdio okuyucusu: istemciden gelen girdiyi okur
  • Codex mesaj işleyicisi: her çekirdek oturumla doğrudan iletişim kurarak istemci isteklerini gönderir ve güncellemeleri alır
  • thread yöneticisi: her thread için bir çekirdek oturumu başlatır
  • çekirdek thread: gerçek ajan döngüsünü çalıştırır
• Tek bir istemci isteği birçok olay güncellemesi üretebilir; bu ayrıntılı olaylar sayesinde zengin arayüzler oluşturmak mümkündür
• stdio okuyucusu ve Codex mesaj işleyicisi, istemci JSON-RPC isteklerini Codex Core işlemlerine dönüştüren ve dahili olay akışını kararlı, arayüz kullanımına uygun JSON-RPC bildirimlerine çeviren bir dönüşüm katmanı görevi görür
• İstemci ile App Server arasındaki JSON-RPC protokolü tam çift yönlüdür
  • Ajan, onay gibi bir girdiye ihtiyaç duyduğunda sunucu isteği başlatabilir ve istemci yanıt verene kadar turn’ü duraklatabilir

Konuşma primitive’leri

• Ajan döngüsü için API tasarımının merkezindeki fikir, kullanıcı ile ajan arasındaki etkileşimin basit bir istek/yanıttan ibaret olmadığı; yapılandırılmış bir dizi iş şeklinde ilerlediğidir
• Üç temel primitive vardır:

• Item

  • Codex’te girdi/çıktının temel birimi
  • Türlüdür: kullanıcı mesajı, ajan mesajı, araç çalıştırma, onay isteği, diff vb.
  • Açık bir yaşam döngüsüne sahiptir: item/started → isteğe bağlı item/*/delta (streaming) → item/completed (nihai payload)
  • İstemci started ile hemen render etmeye başlayabilir, delta ile kademeli güncellemeleri akış halinde alabilir, completed ile tamamlayabilir

• Turn

  • Kullanıcı girdisiyle başlayan tek bir ajan işi birimi
  • Örneğin istemci run tests and summarize failures gönderdiğinde turn başlar; ajan çıktıyı üretmeyi bitirdiğinde turn sona erer
  • Bir turn, ara adımları ve sonuçları temsil eden bir dizi item içerir

• Thread

  • Kullanıcı ile ajan arasındaki devam eden Codex oturumu için kalıcı kapsayıcı
  • Birden çok turn içerir; oluşturulabilir, devam ettirilebilir, fork edilebilir ve arşivlenebilir
  • Thread geçmişi kalıcı olarak tutulduğu için istemciler yeniden bağlanıp tutarlı bir zaman çizelgesi render edebilir

İstemci-sunucu konuşma akışı

• Konuşma başlarken istemci ile sunucunun initialize handshake’ini kurması gerekir
  • İstemci, diğer tüm metodlardan önce tek bir initialize isteği gönderir ve sunucu bunu yanıtıyla onaylar
  • Protokol sürümleme, özellik bayrakları ve varsayılanlar konusunda iki taraf anlaşır
• Yeni bir istek geldiğinde sunucu önce thread’i, ardından turn’ü oluşturur ve thread/started ile turn/started bildirimlerini gönderir
• Araç çağrıları da item olarak istemciye gönderilir; sunucu işin yürütülmesi için onay isteyebilir
  • Onay istendiğinde, istemci "izin ver" veya "reddet" diye yanıtlayana kadar turn duraklatılır
• Sunucu ajan mesajını gönderir ve turn/completed ile turn’ü bitirir
  • Ajan mesajı delta olayları mesajın parçalarını akış halinde iletir ve sonunda item/completed ile nihai olarak tamamlanır
• Bir turn’ün tüm JSON çıktısını görmek için codex debug app-server send-message-v2 "run tests and summarize failures" komutu çalıştırılabilir

İstemcilerle entegrasyon kalıpları

• Yerel uygulamalar ve IDE’ler

  • Taşıma yöntemi stdio üzerinden JSON-RPC (JSONL)’dir
  • Yerel istemciler, platforma özgü App Server ikilisini paketleyerek ya da indirerek uzun ömürlü bir alt süreç olarak çalıştırır
  • VS Code uzantısı ve masaüstü uygulamasında dağıtım artefaktlarına platforma özgü Codex binary’leri dahil edilir ve test edilmiş sürümlere sabitlenir
  • Go, Python, TypeScript, Swift ve Kotlin dahil farklı dillerde App Server istemci uygulamaları tamamlanmıştır
    • TypeScript: tanımlar doğrudan codex app-server generate-ts komutuyla üretilebilir
    • Diğer diller: codex app-server generate-json-schema komutuyla JSON Schema paketi üretilip kod üreticisine verilebilir
  • Xcode gibi ortaklar, istemciyi kararlı tutup en güncel App Server binary’sini işaretleyerek sürüm döngülerini ayırabilir
    • Böylece istemci sürümünü beklemeden sunucu tarafı iyileştirmeler (geliştirilmiş otomatik sıkıştırma, yeni yapılandırma anahtarları vb.) ve hata düzeltmeleri dağıtılabilir
    • JSON-RPC yüzeyi geriye dönük uyumlu olduğundan eski istemciler de yeni sunucularla güvenle iletişim kurabilir

• Codex web runtime’ı

  • Konteyner ortamında çalışır
  • Worker, checkout edilmiş workspace ile bir konteyner hazırlar; bunun içinde App Server binary’si çalıştırılır ve stdio kanalı üzerinden JSON-RPC korunur
  • Web uygulaması (kullanıcının tarayıcısı), HTTP ve SSE üzerinden Codex backend’i ile iletişim kurarak iş olaylarını akış halinde alır
  • Böylece tarayıcı tarafı arayüz hafif tutulurken masaüstü ve web genelinde tutarlı bir runtime sunulur
  • Web oturumları kısa ömürlü olduğundan (sekme kapanması, ağ kopması) durum ve ilerleme sunucu tarafında tutulur
    • Sekme kapansa bile iş devam eder; yeni bir oturum kolayca yeniden bağlanıp kaldığı yerden sürdürebilir

• TUI refactor planı

  • Mevcut TUI, ajan döngüsüyle aynı süreçte çalışan "native" bir istemcidir ve App Server protokolü yerine doğrudan Rust Core türleriyle iletişim kurar
  • TUI’yi, diğer istemciler gibi App Server kullanacak şekilde yeniden düzenleme planı vardır
    • Uzak bir makinede çalışan Codex sunucusuna bağlanabilir
    • Ajan hesaplama altyapısıyla sıkı biçimde entegre olur; dizüstü bilgisayar uyku moduna geçse ya da bağlantı koptuğunda bile iş sürer
    • Yerel tarafta canlı güncellemeler ve kontrol yetenekleri korunur

Doğru protokolü seçmek

• App Server birincil entegrasyon yoludur, ancak daha sınırlı işlev sunan alternatifler de vardır

• MCP sunucusu

  • codex mcp-server çalıştırılarak stdio sunucusunu destekleyen tüm MCP istemcilerinden (ör. OpenAI Agents SDK) bağlanılabilir
  • Hâlihazırda MCP tabanlı bir iş akışınız varsa ve Codex’i çağrılabilir bir araç olarak kullanmak istiyorsanız uygundur
  • Dezavantajı: yalnızca MCP’nin sağladıkları kullanılabilir; diff güncellemeleri gibi Codex’e özgü etkileşimler sorunsuz biçimde eşlenmeyebilir

• Taşınabilir arayüzler

  • Birden çok model sağlayıcısı ve runtime’ı hedefleyen tek bir soyutlama gerektiğinde uygundur
  • Dezavantajı: ortak en düşük özellik kümesine yakınsama riski vardır; bu da zengin etkileşimleri ifade etmeyi zorlaştırabilir
  • Bu alan hızla gelişiyor ve daha fazla ortak standardın ortaya çıkması bekleniyor (ör. agentskills.io)

• App Server

  • Tüm Codex harness’ını kararlı ve UI dostu bir olay akışı olarak açığa çıkarır
  • Tüm ajan döngüsü işlevlerine ek olarak ChatGPT ile giriş yapma, model keşfi ve yapılandırma yönetimi gibi destekleyici yetenekler de sunar
  • Başlıca maliyet: kullandığınız dilde istemci tarafı JSON-RPC binding’leri kurma gereksinimi
    • JSON Schema ve belgeler sağlandığında Codex karmaşık işlerin çoğunu halledebilir; birçok ekip entegrasyonu hızla uygulayabilmiştir

• CLI modu

  • Tek seferlik işler ve CI çalıştırmaları için hafif, betik odaklı bir mod
  • Tek bir komutu etkileşimsiz çalıştırır, yapılandırılmış çıktıyı akış halinde verir ve net başarı/başarısızlık sinyaliyle sonlanır
  • Otomasyon ve pipeline’lar için uygundur

• TypeScript SDK

  • Yerel bir Codex ajanını kendi uygulamanız içinde programatik olarak kontrol etmeyi sağlayan bir TypeScript kütüphanesi
  • Ayrı bir JSON-RPC istemcisi kurmadan native bir kütüphane arayüzüne ihtiyaç duyduğunuzda uygundur
  • App Server’dan daha önce yayımlandığı için desteklediği dil sayısı daha az ve kapsamı daha dardır
  • Geliştirici ilgisine bağlı olarak App Server protokolünü saran ek SDK’ler sunulabilir

Gelecek planları

• App Server, Codex Core’u açığa çıkarır; istemcilerin tam ajan döngüsünü çalıştırmasına olanak tanır ve TUI, yerel IDE entegrasyonları, web runtime dahil geniş bir yüzey yelpazesini destekler
• Tüm kaynak kodu Codex CLI açık kaynak deposunda yayımlanmıştır
• Özellik talepleri ve geri bildirimler memnuniyetle karşılanıyor; ajanları daha erişilebilir hale getirmek için sürekli iyileştirmeler planlanıyor

• Codex App Server resmi belgeleri