Agentlas OS VPS uzerine nasil kurulur?

Agentlas OS nedir

Agentlas OS, uzman aracıları disk üzerinde paketler halinde tutan ve her görev için geçici bir orkestratör oluşturan açık kaynaklı bir aracı çalışma zamanıdır. Bu sistemi, bir Linux VPS üzerindeki kendi kullanıcı hesabınıza kurarak self-host edebilirsiniz. Bu bir servis değildir. Depoda herhangi bir daemon, dinleme portu, web arayüzü veya container imajı bulunmaz.

Bu son cümle, bu sayfadaki diğer her şeyi belirler. Çoğu çoklu aracı sistemi, sürekli çalışan ve aracıları barındıran bir denetleyici süreci yürütür. Agentlas ise bunu tersine çevirir: uzmanlar durağan dosyalardır ve orkestratör yalnızca bir görev çalışırken var olur. Bunun pratik sonucu, boşta duran bir merkezin size bellek değil, yalnızca disk maliyeti çıkarmasıdır.

Proje, açık çekirdeğini Hephaestus olarak adlandırır ve komutlarda, yollarda ve ortam değişkenlerinde göreceğiniz isim budur. Depo agentlas-ai/Agentlas-OS adresindedir, Apache-2.0 lisansına sahiptir ve büyük ölçüde Python ile yazılmıştır.

Projenin güncel durumu hakkında dürüst bir değerlendirme

Depo 4 Haziran 2026 tarihinde oluşturuldu. 12 Ağustos 2026 itibarıyla yaklaşık on haftalık bir geçmişe sahip olup, 1.150 civarında yıldız ve 112 fork sayısına ulaşmıştır. Gerçek iş yükleri için kullanmayı düşündüğünüz bir proje için bu oldukça yeni bir süredir.

Sürüm yayınlama sıklığı, projenin yaşından daha önemlidir. v1.1.103 sürümü 8 Ağustos 2026'da, v1.2.0 sürümü ise 12 Ağustos 2026'da yayınlanmıştır. Bu, 1.1 serisinde otomasyon yoluyla yayınlanmış yüzün üzerinde etiketli sürüm anlamına gelir; bazı günler birden fazla sürüm çıkmıştır. Bu hızda ilerleyen bir proje, Salı ile Perşembe günleri arasında davranış değişikliği gösterebilir.

Bu nedenle sürümü sabitleyin. Yükleyici bunun için bir ortam değişkeni okur ve aşağıdaki kılavuzun tamamı bu yöntemi kullanır. Günde birkaç kez sürüm yayınlayan bir projeyi sabitlemeden kurmak, o saatte main üzerinde ne varsa onu kullanmanıza neden olur.

VPS üzerinde gereksinimler

Arka planda hiçbir şey çalışmadığı için gereksinimler oldukça düşüktür.

• Bir Linux VPS. Ubuntu 24.04 iyi bir temeldir. Yükleyici, işletim sistemini uname -s ile algılar ve Linux için macOS dışı bir dalı kullanır; bu nedenle başsız (headless) sunucular desteklenir.
• Sunucuda curl, tar ve git ile birlikte çalışan bir Python yorumlayıcısı.
• raw.githubusercontent.com ve github.com adreslerine giden HTTPS trafiği. Yükleyici, bir sürüm arşivini indirir ve SHA-256 değerini doğrular; bu nedenle dış dünyaya erişimi olmayan bir sunucuya kurulum yapılamaz.
• Bir modelle iletişim kuran kodlama aracı olan bir host harness. Claude Code, Codex, opencode, goose ve Hermes desteklenen adaptörlerdir.

root yetkisine ihtiyacınız yoktur. Yükleyici yalnızca ev dizininize ve ~/.local/bin yoluna yazma işlemi yapar; bir yol yazılabilir olmadığında işlemi durdurmak yerine uyarı verir. Eğer sunucu seçimi aşamasındaysanız, VPS üzerinde kodlama aracı çalıştırma rehberi, bu yapının üzerine kurulacağı temel imaj ve erişim ayarlarını kapsamaktadır.

Sabitlenmiş sürümün kurulması

Upstream README dosyası, main içindeki bir betiği doğrudan bash içine yönlendiren tek satırlık bir komut belgeliyor. Bu betiği indirin ve önce okuyun. Betik, shell yapılandırmanıza ve bulduğu her agent harness dosyasına yazma işlemi yapar; bu nedenle on saniyenizi ayırıp incelemeye değer.

curl -fsSL -o install-all-runtimes.sh \
  https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.sh

HEPHAESTUS_REF sabitleme değişkenidir. Betik içindeki satır version="${HEPHAESTUS_REF:-v1.2.0}" şeklindedir; bu yüzden değişkeni tanımsız bırakmak bugün size v1.2.0 sürümünü verirken, gelecek hafta başka bir sürüm verebilir. Değişkeni açıkça tanımlayın; böylece Ekim ayında yapacağınız bir yeniden derleme işlemi, Ağustos ayında test ettiğiniz sürümü kuracaktır.

Dürüst bir sınırlama: Yukarıdaki betik URL'si main sürümünü takip ederken, HEPHAESTUS_REF betiğin indirdiği çalışma zamanı yükünü (runtime payload) sabitler. Bunlar birbirinden farklı iki şeydir. Her ikisini de sabitlemek için, URL içindeki main ifadesini v1.2.0 ile değiştirerek betiği main yerine ilgili etiket (tag) üzerinden çekin.

Başarılı bir çalıştırma, aşağıdaki iki satır dahil olmak üzere yazılan yolları çıktı olarak verir:

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)

İkinci satır, insanların gözden kaçırdığı kısımdır. Yeni kurulmuş bir Ubuntu sisteminde ~/.local/bin genellikle PATH içinde bulunmaz; bu nedenle kurulum başarılı olsa bile her hep-* komutu command not found hatasıyla başarısız olur. Sorunu düzeltin ve doğrulayın:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hep-global status

hep-global status, genel yönlendiricinin (global router) ne kurduğunu ve hangi harness yapılarını tespit ettiğini raporlar. Eğer komut çalışıyorsa, PATH yapılandırmanız doğrudur.

Durum bilgisinin konumu

Her şey ev dizininiz altında bir dosya olarak tutulur; bu da yedekleme ve taşıma işlemlerini kolaylaştırır.

• ~/.agentlas/runtime/v1.2.0/ çalışma zamanının kendisini barındırır, ~/.agentlas/runtime/current/ ise aktif sürüme işaret eden bir sembolik bağdır. İki sabitlenmiş sürüm yan yana bulunabilir.
• ~/.local/bin/ kabuk sarmalayıcılarını (shell wrappers) barındırır: hephaestus, hep-build, hep-network, hep-search, hep-storm, hep-cloud ve hep-upload.
• ~/.agentlas/networking/memory/ kalıcı belleği barındırır: playbook-registry.json, playbook-candidates.jsonl ve memory-events.jsonl.
• ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite sahip bazlı, aracı başına deneyim verilerini barındırır.
• <project>/.agentlas/ontology-runtime.sqlite proje bazlı durum bilgisini barındırır; böylece bu veri sunucuya değil, depoya (repository) bağlı olarak taşınır.
• ~/.cache/agentlas/python Linux üzerinde Python önbelleğini barındırır. macOS farklı bir yol kullanır; bu yol, yükleyicinin uname ile seçtiği daldır.

Bellek dokümantasyonu, gizli anahtarların, ham kimlik bilgilerinin ve tam dökümlerin hiçbir bellek kapsamına alınmaması gerektiğini açıkça belirtir. Kimlik bilgisi değerleri gitignore edilmiş yerel dosyalarda tutulur; bellek ise yalnızca isimleri ve yolları kaydeder. ~/.agentlas dizinini ve proje .agentlas dizinlerinizi yedeklediğiniz takdirde, yeni bir VPS üzerinde sistemi yeniden oluşturabilirsiniz.

Hangi model arka uçlarına işaret edebilir

Kurulumun tamamını yeniden çerçeveleyen detay şudur: Agentlas bir model API'sini çağırmaz. Bunu ana bilgisayar (host) donanımı yapar.

Mimari belgesi, bir çekirdeği her donanıma çeviren çalışma zamanı bağdaştırıcılarını açıklar ve ana bilgisayar çalışma zamanının model kimlik bilgilerine sahip olduğunu belirtir. Agentlas, bir donanımın aldığı iki yüzey sunar: bir AgentSkills dosyası ve stdio üzerinden konuşan bir MCP (model context protocol) sunucusu. Dolayısıyla "Agentlas hangi modelleri destekliyor" sorusunun gerçek karşılığı "donanımınız hangi modelleri destekliyor" sorusudur ve yanıt; Claude Code, Codex, opencode, goose veya Hermes'in erişebildiği her şeydir.

MCP sunucusunu kaydetmek, Codex tarzı bir TOML yapılandırmasında şu şekilde görünür:

[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]

Aynı sunucu, kurulum sırasında otomatik olarak ~/.cursor/mcp.json, ~/.config/goose/config.yaml ve diğer donanım yapılandırmalarına kaydedilir. Bunlardan birkaçını tek bir kutuya bağlıyorsanız, bir VPS üzerinde MCP sunucuları çalıştırmak konusu, stdio ve süreç modelini daha derinlemesine ele alır.

Self-hosted bir Ollama uç noktasına yönlendirme

Harness model bağlantısını yönettiğinden, Agentlas'ı yerel modellere yönlendirmek, harness'ınızı Ollama'ya yönlendirmek anlamına gelir. Ollama, v0.15 sürümünde tam olarak bu amaçla bir launch alt komutu eklemiştir ve bu özellik 11 Ağustos 2026 itibarıyla v0.32.9 sürümünde de mevcuttur. Bu komut, herhangi bir ortam değişkeni ayarlamaya gerek kalmadan mevcut bir harness'ı yerel modellere göre yapılandırır:

ollama pull qwen3-coder:30b
ollama launch opencode

Kurulu olan harness'ınıza bağlı olarak opencode yerine claude, codex veya droid değerini kullanın. Ardından bir isteği yerel çalışma zamanı üzerinden yönlendirin:

~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollama

Başarılı bir yönlendirme, seçilen ajanı veya ekibi belirten bir receipt_id içeren JSON formatında bir karar döndürür. Eğer anlamlı bir sonuç dönmüyorsa, bunun yaygın nedeni bağlam uzunluğudur (context length). Agentlas belgeleri, yönlendirme yoğunluklu oturumlar için en az 64k bağlam uzunluğuna sahip bir model kullanılmasını önerir ve örnek olarak qwen3-coder, gemma3 ve deepseek-r1 modellerini belirtir. Ollama'nın kodlama araçlarına yönelik kendi kılavuzu da aynı 64k alt sınırını şart koşar. Yönlendirme kararları, ajan envanterini istem (prompt) içinde taşıdığından, 8k veya 32k bağlam uzunluğuna sahip bir model envanteri kesintiye uğratır ve hatalı seçim yapar.

Sloganların bahsetmediği bir uyarı mevcuttur. Ollama, Gemma ve DeepSeek kendi eklenti veya komut sistemlerine sahip değildir, bu nedenle /agentlas eğik çizgi (slash) komutları buralarda mevcut değildir. Yerel model kurulumunda sistemi MCP sunucusu ve hephaestus route komutu üzerinden yönetirsiniz. Bu, yüzey alanında gerçek bir azalmadır ve ağırlıkları kendi sunucunuzda tutmanın getirdiği dürüst bir takastır.

Boşta bekleyen uzmanlar merkezinin RAM maliyeti

Hiçbir şey. Cevabın tamamı budur; buna güvenmek yerine kanıtlayabilirsiniz.

Ödünç alınan merkez uzmanları, süreç olarak değil paket yapıları olarak gelir. Bir uzman, bir agent.md ve bir .agentlas/ JSON dizininden oluşur: tetikleyiciler ve yetenekler için routing-card.json, yazma sınırları için memory-map.json, tek başına mı yoksa bir ekip olarak mı çalışacağını belirlemek için mode-map.json. Hephaestus Network, arka plan servisi olmayan, süreç içi (in-process) bir zamanlayıcı olarak tanımlanır. Görevler arasında kendiniz kontrol edin:

pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlas

İlk iki komut boşta bir sunucuda hiçbir şey yazdırmaz, çünkü bellekte yerleşik hiçbir şey yoktur. Üçüncüsü, park halindeki bir merkezin size yüklediği tek maliyeti yazdırır; bu da disk maliyetidir ve tuttuğunuz uzman sayısı ile çalışma zamanının (runtime) beraberinde getirdiği gömülü model ile birlikte artar.

Dolayısıyla bellek sorusu tamamen ani yük (burst) ile ilgilidir ve ani yük, kullandığınız donanım (harness) ile model arka ucunuzdan oluşur. Eğer donanımınız barındırılan bir API ile iletişim kuruyorsa, yerleşik maliyet birkaç yüz megabaytlık tek bir süreçtir. Eğer ağırlıkları (weights) kendiniz barındırıyorsanız, fatura ağırlıklara çıkar:

[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.3
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.1
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

Bunlar, bir kıyaslama testinden alınan ölçümler değil, Ollama model kütüphanesinden yayınlanan indirme boyutlarıdır ve 64k bağlam (context) için KV önbelleği, sıfırın üzerindeki her rakamın üzerine eklenir. Agentlas belgelerinde ilk sırada adı geçen model olan qwen3-coder:30b, bağlam öncesinde 19 GB ağırlığa ihtiyaç duyar ve 27B Gemma varyantı bile 17 GB talep eder. Bu rakamlar karşısında, Agentlas katmanının kendisi bütçede görünmez bile.

Tek bir harness çalıştırmak ile karşılaştırma

Barındırılan bir API üzerinde tek bir harness çalıştırdığınızda VPS'niz tek bir süreç (process) taşır. Agentlas eklediğinizde ise aynı süreci ve ek dosyaları taşır. Orkestratör, uzun süre çalışan fazladan bir program değildir; diskteki paketlerden birleştirilen ve ardından atılan daha büyük bir istemdir (prompt).

Değişen maliyet bellek değil, bağlamdır (context). Birkaç uzman kartı ve bunların yönlendirme meta verilerini çeken bir orkestratör, çıplak bir harness'a göre görev başına daha fazla token harcar. Barındırılan bir API'de bu durum RAM yerine para maliyeti anlamına gelir. Yerel ağırlıklarda ise bu durum zamandır; çünkü daha uzun bir istem, CPU üzerinde daha uzun bir ön doldurma (prefill) veya daha meşgul bir GPU demektir.

Bu nedenle, bunun gibi bir sunucu için boyutlandırma tavsiyesi, aracı çerçevesine (agent framework) değil, model kararına göre belirlenir. Kodlama aracı VPS'si için RAM ve CPU boyutlandırma konusu bunu ayrıntılı olarak ele alır ve varılan sonuç burada da geçerlidir: Çalıştırmayı planladığınız arka uç (backend) için uygun planı seçin, ardından harness için birkaç gigabaytlık ek alan bırakın. Karşılaştırma için her zaman açık (always-on) yönetici tasarımını tercih ederseniz, Omnigent çoklu aracı harness'ı koordinatörünü bellekte tutar; bu durum tam tersi bir takas (trade-off) oluşturur ve boşta kalan bellek kullanımında doğrudan kendini gösterir.

Hata modları ve karşılaşacağınız dizgeler

Temiz bir kurulumdan hemen sonra hep-build: command not found. Yükleyici, varsayılan bir Ubuntu imajında PATH üzerinde bulunmayan ~/.local/bin dizinine yazma işlemi gerçekleştirdi. Bu durum son satırda belirtildi ancak satır ekranı geçti. Yukarıda gösterilen export komutunu ekleyin.

Sunucuyu yeniden oluşturduktan sonra davranış değişiklikleri. HEPHAESTUS_REF değerini ayarlamadınız, bu nedenle yükleyici o gün geçerli olan etiketi varsayılan olarak kullandı. Bu değeri sabitleyin ve sabitlediğiniz sürümü diğer sürüm numaralarınızın yanına not edin.

Yönlendirme, yerel bir modelde yanlış uzmanı seçiyor. Modelin bağlam penceresi, aracı envanteri için çok küçüktür. 64k veya daha yüksek kapasiteli bir modele geçin ve Ollama bağlam uzunluğunu buna göre ayarlayın; çünkü varsayılan değer kodlama araçlarının gereksiniminden daha düşüktür.

ollama launch tanınmıyor. Alt komut, Ollama v0.15 ile gelmiştir. Dağıtım depolarındaki eski paketler bu sürümden öncesine aittir, bu nedenle güncel bir Ollama sürümü yükleyin.

Kurulum, beklemediğiniz dizinlere yazıyor. Betik, bulduğu her aracı algılar ve yapılandırır; ~/.claude/, ~/.codex/, ~/.gemini/, ~/.cursor/ ve daha fazlasına yazar. Paylaşımlı bir derleme sunucusunda, betiği çalıştırmadan önce okuyun ve bu dizinlerden hangilerinin sizin için önemli olduğunu belirleyin.

Bunu henüz çalıştırmalı mısınız

Günde birkaç kez otomatik sürüm yayınlayan on haftalık bir proje, üretim iş yükü altına alınacak bir yapı değildir. Mimari oldukça ilgi çekicidir, lisans Apache-2.0'dır ve dosya tabanlı tasarım, kaldırma işleminin yalnızca iki dizini silmekten ibaret olduğu anlamına gelir. Bu gerçekler, projeyi denemeyi kolay, ancak ona bağımlı olmayı riskli kılar.

Şu an için makul bir yaklaşım şudur: v1.2.0 sürümünü sabitleyin, yeniden oluşturabileceğiniz bir sunucuda çalıştırın, ~/.agentlas öğesini yedeklerinizde tutun ve sürüm sabitlemesini değiştirmeden önce değişiklik günlüğünü (changelog) tekrar okuyun. Bu alandaki diğer seçeneklerin neler olduğu ve her birinin ne kadar olgunlaştığına dair daha geniş bir inceleme için self-hosted yapay zeka ajanları özeti daha iyi bir başlangıç noktasıdır; bir VPS üzerinde Hermes ajanı barındırma ise Agentlas'ın uyum sağladığı altyapılardan birini ele almaktadır.

FAQ

Agentlas OS, VPS üzerinde bir sunucu olarak mı çalışır?

Hayır. Depoda herhangi bir daemon, dinleme portu veya container imajı bulunmamaktadır. Yükleyici, ~/.agentlas/runtime/ altında bir çalışma zamanı ve ~/.local/bin içine komut sarmalayıcıları yazar; Hephaestus Network ise arka plan servisi yerine süreç içi bir zamanlayıcıdır. Bunu boşta duran bir makinede doğrulayabilirsiniz: pgrep -af hephaestus hiçbir çıktı vermez ve etkinleştirilecek bir systemd birimi yoktur. Burada self-hosting, kodun ve durumun makinenizde olması anlamına gelir; bir servisin dinleme yapması demek değildir.

Boşta duran uzmanlardan oluşan bir merkez ne kadar RAM kullanır?

Hiç, çünkü boşta duran uzmanlar birer süreç değildir. Bir uzman, agent.md dosyası ve routing-card.json, memory-map.json gibi meta verileri tutan bir .agentlas/ dizininden ibarettir; bu nedenle park halindeki bir merkez sadece disk alanı kaplar. Bunu du -sh ~/.agentlas ile ölçebilirsiniz. Bellek yalnızca bir görev çalışırken tüketilir ve bunu tüketen şey Agentlas katmanı değil, sizin harness süreciniz ve model arka ucunuzdur.

Hangi modelleri kullanabilirim ve kendi Ollama sunucuma yönlendirebilir miyim?

Agentlas, model API'lerini kendisi çağırmaz. Kimlik bilgileri ve bağlantı ana bilgisayar harness'ına aittir; bu nedenle desteklenen modeller, harness'ınızın desteklediği modellerdir. Yerel ağırlıklar için, claude, codex veya droid değerlerini değiştirerek ollama launch opencode komutunu çalıştırın; bu, harness'ı herhangi bir ortam değişkeni olmadan Ollama sunucunuza göre yapılandırır. En az 64k bağlam penceresine sahip qwen3-coder veya gemma3 gibi bir model kullanın; çünkü yönlendirme istemleri, aracı envanterini taşır ve daha küçük pencerelerde ciddi kırpılmalar yaşanır.

Hangi sürümü yüklemeliyim ve sürüm sabitleme (pinning) neden önemlidir?

Yükleyiciyi çalıştırmadan önce HEPHAESTUS_REF=v1.2.0 değerini ayarlayarak, 12 Ağustos 2026 itibarıyla güncel olan v1.2.0 etiketli sürümü yükleyin. Betiğin kendi varsayılanı olan version="${HEPHAESTUS_REF:-v1.2.0}", geliştiricilerin bir sonraki etiketlediği sürümü takip eder. Sabitleme burada normalden daha önemlidir çünkü proje, 1.1 serisinde yüzün üzerinde sürüm yayınlamıştır; bazı günler birden fazla sürüm çıkmıştır. Bu nedenle sabitlenmemiş bir yeniden derleme, haftalar sonra size test ettiğiniz sistemi sunmayacaktır.