Hızlı başlangıç

Başlamadan önce

uv ile kurulmuş bir ivralo komutu gerekiyor. Henüz herkese açık bir paket yok: repo private, erişimi istek üzerine veriyoruz (bize yazın). Kurulumun kendisi tek satır:

uv tool install --python 3.13 'ivralo @ git+ssh://git@github.com/kemalcalak/ivralo.git'

Bunlara da ihtiyacınız olacak:

• pgvector'lü PostgreSQL. En kolayı Docker: ivralo init, veritabanını ana dizine koyduğu compose dosyasıyla ayağa kaldırır. Zaten çalışan bir veritabanınız varsa o da olur (PostgreSQL).
• Bir model. Ollama üzerinden yerel bir model, şirketinizin OpenAI uyumlu endpoint'i ya da barındırılan bir API.
• İnceleme için git ve çalıştırdığınız bir servisin repo'su.

Bu sayfa, geliştiricinin sorularla ilerlediği yolu anlatıyor. Başında kimsenin olmayacağı bir sunucu için Sunucuya kurulum sayfasını izleyin.

1. Bir ana dizin oluşturun

Ana dizin (home), ivralo'nun çalışırken kullandığı dizindir: gelen skill'ler, brand.json, veritabanının compose dosyası ve ana dizinin .env'i burada durur. Kurulu program bunların hepsinin bir kopyasını içinde taşır, init de onları yerine koyar:

ivralo init --home ~/ivralo

init önce hangi modeli istediğinizi sorar. Sonra iş yapan her adımdan önce onayınızı alır: .env'i yazar, veritabanı parolasını üretir, PostgreSQL'i docker compose up -d ile başlatır, eksik Ollama modellerini çeker ve web araçlarının kullandığı tarayıcıyı kurar. Dizinde zaten olan hiçbir şeye dokunmaz. En sonda, bundan sonraki her ivralo çağrısını bu ana dizine yönlendiren satırı, dizinin tam yoluyla basar:

export IVRALO_HOME="$HOME/ivralo"   # kalıcı olması için ~/.profile içine

Bu satırı ~/.profile'a ekleyin, sonra yeni bir terminal açın ya da değişkeni bu terminalde export edin. Windows'ta bunun yerine init'in bastığı setx satırını çalıştırın.

2. Makineyi kontrol edin

ivralo doctor

doctor, ivralo'nun ihtiyaç duyduğu her parçayı bölüm bölüm kontrol eder ve her sorunu, düzeltmesiyle birlikte tek satırda verir. Temiz bir çalıştırmanın sonu şöyle görünür:

environment
    ok  python  3.13.5
    ok  home  /home/you/ivralo · from IVRALO_HOME
    ok  .env read  /home/you/ivralo/.env
...
Everything checks out. Start with: ivralo

fail ile işaretlenenleri önce çözün. Her bölüm ivralo doctor sayfasında tek tek anlatılıyor.

3. Bir model seçin

Model, ana dizinin .env'inde bir model referansı olarak tanımlanır. init bunu verdiğiniz cevaptan yazar; istediğiniz zaman değiştirebilirsiniz.

Endpoint satırlarını init sizin yerinize yazabilir: ivralo init --home ~/ivralo --model-url http://gpu-box:8000/v1 --model my-model.

Barındırılan bir model her açılışta adıyla bildirilir; makineden neyin çıktığını da doctor'ın providers bölümünde görürsünüz. Incident kanıtı, o çalıştırma için --hosted ile izin vermediğiniz sürece barındırılan bir modele gönderilmez. Bu izin ayrıca IVRALO_INCIDENT_MASK=true ister; böylece model sizin host'larınızı, adreslerinizi ve tanımlayıcılarınızı değil, yer tutucuları görür.

4. Örnek bir incident inceleyin

İnceleme, hata veren servisin repo'sunun içinde çalışır; çünkü bulduklarının yarısı deploy edilen kodla ilgilidir. O repo'ya geçin ve küçük bir bundle, yani kanıtları tutan bir klasör oluşturun:

cd ~/src/checkout-service
mkdir incident

İçine iki dosya koyun. Biri deploy log'u; revision= ya da commit= geçen bir satır deploy olarak sayılır:

2026-10-12T10:01:00Z deploy checkout-service revision=6ad91e2

Diğeri, servisin bozulduğu saatlerin log'u, olduğu gibi kopyalanmış hali:

2026-10-12T10:04:12Z ERROR GET /cart 500 KeyError: 'currency'
2026-10-12T10:04:19Z ERROR GET /cart 500 KeyError: 'currency'

Repo'nuzda gerçekten olan bir commit kullanın; elinizde gerçek log satırları varsa onları da. Kanıt ne kadar çok şey anlatırsa rapor da o kadar çok şey ortaya koyar. Sonra şunu çalıştırın:

ivralo incident incident/

İlk seferde ivralo bu klasöre güvenip güvenmediğinizi sorar; kendi repo'nuz için evet deyin. Investigator, ivralo'nun bundle'dan ve koddan hesapladığı bulguları okur, sınıfa ve nedene karar verir, sonra bir rapor yazar. Komut, raporun yerini ve sonucu basar:

.ivralo/incidents/incident-20261012-101500/report.md
DIAGNOSED - class code

Kanıt zayıfsa sonuç büyük ihtimalle INSUFFICIENT_EVIDENCE olur. Bu bir hata değil, dürüst cevaptır. Çıkış kodu rapor yazıldıysa 0, yazılmadıysa 1'dir; inceleme hiç başlayamadıysa (repo değilse, bundle yoksa, --hosted olmadan barındırılan bir model seçildiyse, veritabanı yoksa) 2'dir.

report.md'yi açın. Her iddia bir bundle satırına ya da bir repo satırına dayanır. Bir iddianın nereden geldiğini görmek için:

ivralo why -s <id> last "KeyError: 'currency'"

Komut her incelemeden sonra oturum kimliğini ve bu satırı sizin için basar. Rapor ve dört sonucu Server modu ve incident'lar sayfasında anlatılıyor.

5. Geliştirici moduna ilk bakış

Aynı repo'da bir oturum açın:

ivralo

Bu tam ekran bir oturum. İsteğinizi kendi cümlelerinizle yazın, örneğin "sepetin para birimini nerede okuduğunu bul ve açıkla". Ana ajan kodu okur ve cevap verir; bir dosyayı değiştirmek istediğinde diff'i gösterir ve onayınızı bekler. /help komutları listeler, exit ile çıkarsınız.

Bir script'ten tek seferlik bir soru sormak için ivralo ask "..." kullanın; aynı ekibi başında kimse yokmuş gibi çalıştırır. Size sorması gereken her şey, örneğin bir düzenleme ya da salt okunur listede olmayan bir shell komutu, sorulmaz, doğrudan reddedilir.

Sırada ne var

• Kavramlar: bu sayfalarda geçen terimler.
• Repo'da çalışmak: geliştirici modunun tamamı.
• Sunucuya kurulum: aynı şey production'ın yanında, soru sormadan.