Memanfaatkan harness Codex: bagaimana OpenAI membangun App Server

• OpenAI membangun dan menyediakan arsitektur App Server yang distandardisasi serta protokol JSON-RPC agar Codex bisa diintegrasikan ke produk sendiri
• Awalnya berangkat dari harness TUI yang berpusat pada CLI, tetapi dengan mengadopsi protokol JSON-RPC, berbagai klien seperti IDE, web, dan aplikasi lokal dapat berbagi agent loop yang sama
• App Server adalah proses berjalan jangka panjang yang meng-host library inti Codex, dan mengekspos seluruh pengalaman agen ke klien seperti manajemen lifecycle thread, konfigurasi/autentikasi, dan eksekusi tool
• Melalui tiga primitive percakapan yaitu item, turn, dan thread, interaksi kompleks dalam agent loop dapat distrukturkan dan dipakai untuk membangun UI yang kaya
• Harness yang sama digunakan ulang di berbagai surface seperti VS Code, JetBrains, Xcode, aplikasi desktop, dan runtime web, dengan dukungan binding klien multibahasa seperti Go, Python, TypeScript, Swift, dan Kotlin
• OpenAI juga menyediakan metode integrasi alternatif seperti server MCP, mode CLI, dan SDK TypeScript, tetapi App Server menjadi standar integrasi utama
• OpenAI akan mempertahankan App Server sebagai jalur default integrasi Codex, serta mendukung siapa pun untuk mengintegrasikan Codex ke workflow mereka sendiri melalui repo CLI open source

---

Latar belakang dasar App Server

• Pada awalnya ini adalah cara praktis untuk menggunakan ulang harness Codex di berbagai produk, tetapi kemudian berkembang menjadi protokol standar
• Codex CLI dimulai sebagai TUI (terminal user interface), dan saat membangun ekstensi VS Code, dibutuhkan cara untuk menjalankan harness yang sama di UI IDE
  • Perlu mendukung pola interaksi yang melampaui request/response biasa, seperti penjelajahan workspace, streaming progres reasoning, dan output diff
• Pada awalnya sempat dicoba mengekspos Codex sebagai server MCP, tetapi sulit mempertahankan semantik MCP dengan cara yang cocok untuk VS Code
• Sebagai alternatif, OpenAI mengadopsi protokol JSON-RPC yang mencerminkan loop TUI, dan ini menjadi versi tidak resmi pertama dari App Server
  • Saat itu belum diperkirakan akan dipakai klien lain, sehingga tidak dirancang sebagai API yang stabil
• Seiring adopsi Codex meluas, tim internal dan mitra eksternal seperti JetBrains dan Xcode meminta kemampuan untuk menyematkan harness ke produk mereka sendiri
  • Karena itu dibutuhkan desain surface platform yang memungkinkan protokol berkembang sambil tetap menjaga kompatibilitas dengan versi sebelumnya

Struktur internal harness Codex

• Inti Codex adalah library yang memuat seluruh kode agen sekaligus runtime yang menjalankan agent loop dan mengelola persistensi satu thread Codex (percakapan)
• Di luar agent loop inti, ada tiga area fungsi utama:
  • Lifecycle dan persistensi thread: membuat, melanjutkan, fork, dan mengarsipkan thread, serta menjaga catatan event agar klien bisa tersambung kembali dan merender timeline yang konsisten
  • Konfigurasi dan autentikasi: memuat konfigurasi, mengelola nilai default, status kredensial, dan menjalankan alur autentikasi seperti "Login dengan ChatGPT"
  • Eksekusi dan ekstensi tool: menjalankan tool shell/file di sandbox, serta menghubungkan integrasi seperti server MCP dan skill agar dapat berpartisipasi dalam agent loop di bawah model kebijakan yang konsisten

Arsitektur App Server

• App Server adalah protokol JSON-RPC antara klien dan server sekaligus proses berjalan jangka panjang yang meng-host thread inti Codex
• Ada empat komponen utama:
  • Pembaca stdio: bertugas membaca input dari klien
  • Pemroses pesan Codex: berkomunikasi langsung dengan tiap sesi inti untuk mengirim request klien dan menerima pembaruan
  • Manajer thread: memulai satu sesi inti untuk setiap thread
  • Thread inti: menjalankan agent loop yang sebenarnya
• Satu request klien dapat menghasilkan banyak pembaruan event, dan event terperinci ini memungkinkan pembangunan UI yang kaya
• Pembaca stdio dan pemroses pesan Codex berperan sebagai lapisan transformasi yang mengubah request JSON-RPC dari klien menjadi operasi inti Codex, lalu mengubah stream event internal menjadi notifikasi JSON-RPC yang stabil dan dapat digunakan UI
• Protokol JSON-RPC antara klien dan App Server bersifat dua arah penuh
  • Saat agen membutuhkan input seperti persetujuan, server dapat memulai request dan menjeda turn sampai klien memberi respons

Primitive percakapan

• Inti desain API untuk agent loop adalah bahwa interaksi antara pengguna dan agen bukan sekadar request/response sederhana, melainkan berkembang sebagai serangkaian aksi terstruktur
• Tiga primitive utama:

• Item

  • Unit dasar input/output di Codex
  • Memiliki tipe: pesan pengguna, pesan agen, eksekusi tool, permintaan persetujuan, diff, dan lain-lain
  • Memiliki lifecycle eksplisit: item/started → item/*/delta opsional (streaming) → item/completed (payload final)
  • Klien dapat langsung mulai merender pada started, menerima pembaruan bertahap pada delta, dan menyelesaikannya pada completed

• Turn

  • Satu unit pekerjaan agen yang dimulai dari input pengguna
  • Contoh: ketika klien mengirim "run tests and summarize failures", turn dimulai, lalu berakhir saat agen selesai menghasilkan output
  • Satu turn berisi serangkaian item yang mewakili langkah perantara dan hasil

• Thread

  • Kontainer persisten untuk sesi Codex yang sedang berlangsung antara pengguna dan agen
  • Dapat memuat beberapa turn, serta bisa dibuat, dilanjutkan, di-fork, dan diarsipkan
  • Riwayat thread dipertahankan terus-menerus agar klien dapat tersambung kembali dan merender timeline yang konsisten

Alur percakapan klien-server

• Saat memulai percakapan, klien dan server harus menyiapkan handshake initialize
  • Klien mengirim satu request initialize sebelum metode lain, lalu server mengonfirmasinya melalui respons
  • Kedua pihak menyepakati pengelolaan versi protokol, flag fitur, dan nilai default
• Untuk request baru, server membuat thread lalu membuat turn, kemudian mengirim notifikasi thread/started dan turn/started
• Pemanggilan tool juga dikirim ke klien sebagai item, dan server dapat meminta persetujuan untuk mengeksekusi aksi
  • Saat persetujuan diminta, turn dijeda sampai klien merespons dengan "izinkan" atau "tolak"
• Server mengirim pesan agen lalu mengakhiri turn dengan turn/completed
  • Event delta pesan agen men-stream bagian-bagian pesan, lalu ditutup secara final dengan item/completed
• Untuk melihat JSON lengkap dari seluruh turn, bisa menjalankan perintah codex debug app-server send-message-v2 "run tests and summarize failures"

Pola integrasi dengan klien

• Aplikasi lokal dan IDE

  • Metode transport yang digunakan adalah JSON-RPC melalui stdio (JSONL)
  • Klien lokal membundel atau mengambil biner App Server per platform lalu menjalankannya sebagai subprocess jangka panjang
  • Pada ekstensi VS Code dan aplikasi desktop, artefak distribusi menyertakan biner Codex spesifik platform dan dipatok ke versi yang sudah lolos pengujian
  • Implementasi klien App Server sudah tersedia dalam banyak bahasa seperti Go, Python, TypeScript, Swift, dan Kotlin
    • TypeScript: definisi dapat dihasilkan langsung dengan perintah codex app-server generate-ts
    • Bahasa lain: bundle JSON Schema dapat dibuat dengan perintah codex app-server generate-json-schema lalu dimasukkan ke code generator
  • Mitra seperti Xcode dapat menjaga klien tetap stabil sambil menunjuk ke biner App Server terbaru, sehingga siklus rilis terpisah
    • Perbaikan sisi server seperti auto-compaction yang ditingkatkan, key konfigurasi baru, dan bug fix dapat dirilis tanpa menunggu rilis klien
    • Karena surface JSON-RPC kompatibel dengan versi sebelumnya, klien lama tetap dapat berkomunikasi aman dengan server baru

• Runtime web Codex

  • Berjalan di lingkungan container
  • Worker memprovisikan container dengan workspace yang sudah di-checkout, menjalankan biner App Server di dalamnya, dan mempertahankan JSON-RPC melalui kanal stdio
  • Aplikasi web (browser pengguna) berkomunikasi dengan backend Codex melalui HTTP dan SSE untuk men-stream event pekerjaan
  • Pendekatan ini memberi runtime yang konsisten di desktop dan web sambil menjaga UI sisi browser tetap ringan
  • Karena sesi web bersifat singkat, seperti tab ditutup atau jaringan terputus, status dan progres disimpan di server
    • Bahkan jika tab hilang, pekerjaan tetap berjalan, dan sesi baru dapat dengan mudah tersambung kembali lalu melanjutkan dari titik terakhir

• Rencana refaktor TUI

  • TUI yang ada sekarang adalah klien "native" yang berjalan dalam proses yang sama dengan agent loop, dan berkomunikasi langsung dengan tipe inti Rust, bukan protokol App Server
  • Ada rencana untuk merefaktor TUI agar menggunakan App Server seperti klien lain
    • Akan bisa terhubung ke server Codex yang berjalan di mesin jarak jauh
    • Agen akan terintegrasi erat dengan infrastruktur komputasi, sehingga pekerjaan tetap berjalan meski laptop sleep atau koneksi terputus
    • Tetap menyediakan pembaruan langsung dan kontrol secara lokal

Memilih protokol yang tepat

• App Server adalah metode integrasi utama, tetapi ada juga alternatif dengan fitur yang lebih terbatas

• Server MCP

  • Jalankan codex mcp-server dan hubungkan dari klien MCP apa pun yang mendukung server stdio, misalnya OpenAI Agents SDK
  • Cocok jika sudah memiliki workflow berbasis MCP dan ingin menggunakan Codex sebagai tool yang dapat dipanggil
  • Kekurangannya: hanya dapat memakai apa yang disediakan MCP, dan interaksi khusus Codex seperti pembaruan diff mungkin tidak terpetakan dengan mulus

• Antarmuka portabel

  • Cocok bila membutuhkan satu abstraksi tunggal untuk berbagai penyedia model dan runtime
  • Kekurangannya: cenderung turun ke subset fitur yang sama sehingga sulit mengekspresikan interaksi yang kaya
  • Area ini berkembang cepat, dan diperkirakan akan muncul lebih banyak standar bersama, misalnya agentskills.io

• App Server

  • Mengekspos seluruh harness Codex sebagai stream event yang stabil dan ramah UI
  • Selain fungsi penuh agent loop, juga menyediakan fitur pendukung seperti Login dengan ChatGPT, penjelajahan model, dan pengelolaan konfigurasi
  • Biaya utamanya: perlu membangun binding JSON-RPC di sisi klien dalam bahasa yang digunakan
    • Dengan menyediakan JSON Schema dan dokumentasi, Codex dapat menangani banyak pekerjaan kompleks, dan banyak tim bisa mengimplementasikan integrasi dengan cepat

• Mode CLI

  • Mode skrip ringan untuk pekerjaan sekali jalan dan eksekusi CI
  • Menjalankan satu perintah secara non-interaktif, men-stream output terstruktur, lalu selesai dengan sinyal sukses/gagal yang jelas
  • Cocok untuk otomasi dan pipeline

• SDK TypeScript

  • Library TypeScript yang memungkinkan pengendalian agen Codex lokal secara terprogram di dalam aplikasi sendiri
  • Cocok jika membutuhkan antarmuka library native tanpa harus membangun klien JSON-RPC terpisah
  • Dirilis lebih dulu daripada App Server, sehingga bahasa yang didukung lebih sedikit dan cakupannya lebih sempit
  • Bergantung pada minat developer, ada kemungkinan hadir SDK tambahan yang membungkus protokol App Server

Rencana ke depan

• App Server mengekspos inti Codex, memungkinkan klien menjalankan seluruh agent loop, dan mendukung berbagai surface secara luas termasuk TUI, integrasi IDE lokal, dan runtime web
• Seluruh source code dipublikasikan di repo open source Codex CLI
• OpenAI membuka ruang untuk permintaan fitur dan masukan, serta akan terus melakukan peningkatan berkelanjutan agar agen lebih mudah digunakan

• Dokumentasi resmi Codex App Server