AgentVera Runner kurulum rehberi

Runner ne yapar?

Ajanlar dizüstü bilgisayarında değil, gücü yüksek ve hep açık olan bir sunucuda çalışsın istediğinde Runner’ı kullanırsın. Runner ajanların terminal oturumlarını o sunucuda tutar; kapağı kapatsan, internetin kopsa ya da başka bir bilgisayardan bağlansan bile oturum sürer.

• Kod ve konuşmalar senin sunucunda kalır.
• Bağlantı AgentVera sunucusu üzerinden şifreli (TLS) aktarılır; aktarılan terminal trafiği sunucuda yorumlanmaz, kaydedilmez ve saklanmaz.
• Sunucunun CPU, bellek ve disk kullanımını, açık oturumları ve izin verdiğin klasörlerdeki dosyaları görürsün.
• Webhook’lardan ya da web’deki “Ajana gönder”den gelen görevlerde, ajan turunu bitirince çıktısının son kısmı (en fazla 6.000 karakter) görev özeti olarak sunucuya bildirilir.

Gereksinimler

• Linux ya da macOS çalışan bir sunucu veya bilgisayar.
• Node.js 20 ya da üstü ve npm.
• curl ya da wget.
• Ajan oturumları için o sunucuda kurulu ve giriş yapılmış bir CLI: Claude Code, Codex, Gemini CLI ya da opencode. Terminal oturumu her zaman kullanılabilir.
• Pro ya da Team planına sahip bir AgentVera organizasyonu.

Node.js yoksa nodejs.org’dan kurabilir ya da fnm ile kurabilirsin:

curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22

Claude Code’u kurmak ve bir kez giriş yapmak için:

npm install -g @anthropic-ai/claude-code
claude login

Kurulum

1. Tarayıcıda app.agentvera.dev/runners sayfasını aç ve “Yeni runner ekle”ye tıkla. 8 karakterlik bir eşleştirme kodu çıkar; kod 10 dakika geçerlidir.
2. Sunucunda aşağıdaki komutu çalıştır; KOD yerine eşleştirme kodunu yaz.
3. Birkaç saniye içinde runner /runners sayfasında “çevrimiçi” görünür. Açınca sunucunun CPU, bellek ve disk kullanımını görür, “Yeni ajan” ile Claude, Codex ya da terminal oturumu başlatırsın.

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD

Eşleştirme kodunun süresi dolduysa /runners sayfasından yeni bir kod oluşturman yeterli.

Kurulum seçenekleri

Kurulum komutuna şu seçenekleri ekleyebilirsin:

• --name AD: runner’ın adı. Varsayılan makine adıdır.
• --server URL: AgentVera sunucusu. Varsayılan https://app.agentvera.dev.
• --no-service: arka plan servisi kurma. Runner’ı yalnızca masaüstü uygulamasından SSH ile kullanacaksan.

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD --name derleme-sunucusu

Kurulum neler yapar?

• Runner’ı ~/.agentvera-runner/app klasörüne kurar (klasör yalnızca sana açıktır) ve komutu ~/.local/bin/agentvera-runner olarak bağlar.
• Linux’ta systemd varsa agentvera-runner adında bir kullanıcı servisi oluşturur; servis kapanırsa kendiliğinden yeniden başlar.
• systemd yoksa runner arka planda başlar ve ~/.agentvera-runner/runner.log dosyasına yazar. Bu durumda sunucu yeniden başlayınca runner’ı elle başlatman gerekir.
• macOS’ta dev.agentvera.runner adında bir launchd servisi kurar; oturum açılınca başlar, kapanırsa yeniden başlar ve ~/.agentvera-runner/runner.log dosyasına yazar.
• Erişim token’ını yalnızca senin okuyabildiğin bir dosyaya kaydeder.

Linux’ta oturumu kapattıktan sonra da runner’ın çalışmaya devam etmesi için bir kez şunu çalıştır:

sudo loginctl enable-linger $USER

Komut satırı

agentvera-runner status              # sürüm, servis, eşleştirme, sunucu ve izinli klasörler
agentvera-runner roots ~/projeler     # ajanları ve dosya erişimini bu klasörlerle sınırla
agentvera-runner pair KOD --name AD   # yeniden eşleştir
agentvera-runner daemon               # runner’ı ön planda çalıştır

roots verilmezse ajanlar ev klasöründe çalışır. Yeniden eşleştirdikten sonra servisi yeniden başlat; runner yeni bağlantıyı açılışta kurar.

Servisi yönetmek

Linux (systemd):

systemctl --user status agentvera-runner
systemctl --user restart agentvera-runner
systemctl --user stop agentvera-runner
journalctl --user -u agentvera-runner -f

macOS (launchd):

launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist   # durdur
launchctl load -w ~/Library/LaunchAgents/dev.agentvera.runner.plist   # başlat
tail -f ~/.agentvera-runner/runner.log

Masaüstü uygulamasından bağlanmak

AgentVera masaüstü uygulamasındaki Runner sayfası runner’lara iki yoldan bağlanır: aynı hesapla bulut üzerinden ya da kayıtlı bir SSH sunucusu üzerinden doğrudan. SSH ile kullanacaksan kurulumu --no-service ile yapabilirsin; uygulama bağlandığında runner’ı kendisi başlatır.

Kaldırma

1. app.agentvera.dev/runners sayfasında runner’ı sil. Token’ı hemen geçersiz olur ve runner yeniden bağlanmaz.
2. Servisi durdur ve kaldır.
3. Runner dosyalarını sil.

# Linux
systemctl --user disable --now agentvera-runner
rm ~/.config/systemd/user/agentvera-runner.service

# macOS
launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist
rm ~/Library/LaunchAgents/dev.agentvera.runner.plist

# her ikisi
rm -rf ~/.agentvera-runner ~/.local/bin/agentvera-runner

Güvenlik

• Runner yalnızca dışarıya bağlantı açar; gelen bağlantı için port açmana ya da güvenlik duvarını değiştirmene gerek yoktur.
• Runner’ı yalnızca organizasyonunun aktif üyeleri görüp bağlanabilir. Destek ekibinin kullanıcı adına görüntüleme oturumları bağlanamaz.
• Üyeliği biten ya da organizasyonu askıya alınan kullanıcıların açık bağlantıları kapatılır.
• roots ile ajanların ve dosya erişiminin hangi klasörlerle sınırlı olacağını belirle.
• Webhook’la tetiklenen görevler runner’a prompt gönderebilir; yalnızca güvendiğin kaynakları bağla.

Sorun giderme

• “Node.js 20 ya da üstü gerekli”: Node.js 22 kur ve komutu yeniden çalıştır.
• Eşleştirme kodu geçersiz: kodun 10 dakikalık süresi dolmuş olabilir; /runners sayfasından yeni kod al.
• Runner çevrimiçi görünmüyor: agentvera-runner status çıktısına ve loglara bak; sunucunun app.agentvera.dev:443 adresine çıkabildiğinden emin ol.
• “Yeni ajan”da bir ajan türü yok: o CLI’yı sunucuya kur ve giriş yap; runner yalnızca kurulu bulduğu ajanları listeler.