Rakazo Self-Host Rehberi: VPS Üzerinde AI Bot Kurulumu
Rakazo botunuzu kendi VPS sunucunuzda çalıştırmak için Node 22, pnpm, Postgres ve Docker Compose kurulum adımlarını öğrenin. Sandbox yönetimi ve kaynak planlaması detayları.
Rakazo self-hosting ile aslında neler çalışır
Rakazo'yu self-host etmek, tek bir Linux sunucusu üzerinde beş farklı bileşeni çalıştırmak anlamına gelir: PostgreSQL, bir Graphile Worker süreci, API, web uygulaması ve botların bilgisayarı işlevi gören bir sandbox container. Rakazo, elie222 tarafından Apache 2.0 lisansı altında yayımlanan, Grok Bot'un açık kaynaklı bir alternatifidir. Her bot kendi konuşmalarına, belleğine, rutinlerine ve geçmişine sahiptir; özel bir Private Computer atanmadığı sürece çalışma alanındaki diğer botlarla bir adet Team Computer paylaşır ve eş (peer) veya kısa ömürlü alt ajanlar (subagent) oluşturabilir. Eğer bellek, alt ajan ve araç çağrısı (tool call) gibi terimler bu cümlede yabancı geliyorsa, ajanların gerçekte nasıl çalıştığına dair aşamalı bir rehber üzerinde bir öğleden sonra vakit geçirmek faydalı olacaktır; çünkü aşağıdaki ayarların çoğu, bir botun uyandığında ne yaptığını zihninizde canlandırabildiğinizde anlam kazanır.
Bu son kısım, uygulamanın neden bir masaüstü bilgisayarda değil de bir VPS (sanal özel sunucu) üzerinde çalıştırılması gerektiğini açıklar. Bellek tutan ve zamanlanmış işler yürüten bir botun, siz uyurken de erişilebilir olması gerekir. Uyku moduna geçen bir dizüstü bilgisayar, kuyruğu düşürür.
Rakazo, Ekim 2026 itibarıyla kararlı sürüm numaraları yayımlamasına rağmen kendisini hala beta olarak tanımlamaktadır; bu nedenle buradaki yapılandırmayı bitmiş bir ürün değil, çalışan bir kurulum olarak değerlendirin. Teknoloji yığını tamamen TypeScript tabanlıdır: web uygulaması için React 19 ve Vite, API için Hono, Prisma ile Postgres, hesaplar için Better Auth ve arka plan işleri için Graphile Worker kullanılır. Graphile Worker, kuyruğunu Postgres içinde saklar; bu nedenle Redis veya ikinci bir veri deposu çalıştırmanıza gerek yoktur. .env.example, WAKEUP_DRIVER=graphile değerini ayarlar; bu da uyanan bir botun Postgres destekli bir iş olduğu anlamına gelir. Postgres'i durdurduğunuzda, zamanlanmış tüm bot eylemleri de onunla birlikte durur. Başkasının ürününü çalıştırmak yerine bir ajanı parçalardan birleştirmeyi tercih ederseniz, kendi ajanı bileşenlerden oluşturma diğer seçenektir.
1 GB planı neden bunu taşıyamaz
Süreçleri sayın. Postgres bir süreçtir. API bir Node sürecidir. Worker ikinci süreçtir. Web uygulaması üçüncü süreçtir. Sandbox supervisor dördüncü süreçtir. Ardından botların bilgisayarı gelir: varsayılan olarak grafik Linux masaüstü içeren ve etkin her bot için ayrı bir X display ile Chrome süreci çalıştıran, paylaşımlı bir Team Computer container'ı.
Projenin self-host dokümanı artık host boyutu belirtmiyor. 27 October 2026 tarihinde kontrol edilen v0.3.5 dokümanında yalnızca yazılım gereksinimleri listeleniyor. Dokümanda belirtilen değer, bilgisayar başına bir üst sınırdır: Docker sandbox'larında RAKAZO_COMPUTER_MEMORY varsayılan olarak 2g, RAKAZO_COMPUTER_CPUS ise 2 değerindedir. Bu üst sınır her bot için değil, her bilgisayar için geçerlidir. Her workspace varsayılan olarak bir Team Computer alır ve etkin her Team bot masaüstünü ve tarayıcısını bunun içinde çalıştırır; dolayısıyla tüm botlar aynı 2 GB belleği ve iki çekirdeği paylaşır. Yalnızca Private Computer'a taşınan bot kendisine ait bir container ve üst sınır alır. SANDBOX_PROVIDER=docker ayarını yaparsanız bu masaüstleri control plane'e ek olarak VPS'niz üzerinde çalışır; bu nedenle 4 GB hedef değil, başlangıç alt sınırı olur. Birden fazla botu açık tutmayı planlıyorsanız 8 GB ile başlayın, paylaşımlı bilgisayarın bu belleği gerçekten kullanabilmesi için RAKAZO_COMPUTER_MEMORY değerini artırın ve botlar çalışırken gerçek sayıyı docker stats ile ölçün. Bellek kullanımını belirleyen unsur sandbox içindeki tarayıcıdır; bu nedenle teknik özellikler tablosu size gerçek değeri göstermez. Küçük bir sunucunun aynı anda çok fazla tarayıcı çalıştırmasını önlemek için pozitif bir SANDBOX_TEAM_SCREEN_LIMIT değeri belirleyin; bu değer Docker Team Computer üzerindeki etkin masaüstü sayısını sınırlar. Ürünle birlikte gelen 0 değeri sınırı kaldırır. Genel bellek yetersizse RAKAZO_COMPUTER_MEMORY daha küçük bir değeri, örneğin 1536m değerini de kabul eder. Agent çalıştırmak için bir sunucunun boyutlandırılmasına ilişkin genel yöntem için bir agent VPS'sinin gerçekte ne kadar RAM ve CPU'ya ihtiyaç duyduğu ölçüm sürecini ayrıntılı biçimde açıklar.
Bir ayar, bu durumun daha da kötüleşmesini önler. .env.example, SANDBOX_IDLE_MS=600000 ile birlikte gelir ve yorumunda bilgisayarların bu kadar boşta kalma milisaniyesinden sonra duraklatılacağı veya durdurulacağı belirtilir. Bilgisayar 10 dakika boşta kaldığında kapanır. Kabul edilen en düşük değer 30000'tir; 0 değeri boşta uykuya geçmeyi devre dışı bırakır. Aynı yorumda, boşta duran bir bilgisayarın maliyet oluşturmadığı Docker self-host kurulumları için 0 önerilir; böylece uzun süre çalışan uygulamalar ve oturumlar açık kalır. Bu yaklaşım maliyet açısından geçerlidir, bellek kullanımı açısından değil. Küçük bir VPS üzerinde zamanlayıcıyı etkin bırakın; aksi halde başlattığınız her bilgisayar ve içindeki her tarayıcı çalışmaya devam eder.
Disk kullanımı da önemlidir. Sandbox image'ı, Node modules ve Postgres volume'u aynı diski paylaşır; bu nedenle 40 GB makul bir başlangıç değeridir.
Klonlamadan önce bir sürümü sabitleyin
Rakazo hızlı gelişen bir projedir ve main bir sürüm (release) değildir. 9 Kasım 2026 itibarıyla, 4 Kasım 2026 tarihinde yayınlanan v0.8.0, Latest olarak işaretlenmiş sürümdür. Bu kılavuz, 25 Ekim 2026 tarihinde yayınlanan v0.3.5 sürümüne sabitlenmiştir.
git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'Bu commit, v0.3.5 işaretçisinin gösterdiği noktadır. Branch veya tag yerine commit değerini sabitleyin. Bir sonraki git pull işleminde branch değişebilir; tag ise bir geliştiricinin yerini değiştirebileceği hareketli bir etikettir. Bu nedenle ikisi de geri dönebileceğiniz bir ağacı tanımlamaz. Bir commit tanımlayıcısı değişemez. Kendi commit değerinizi sunucu bilgilerinizin yanına not edin; çünkü bir yükseltme işlemi hata verdiğinde en hızlı çözüm git checkout <old commit> ve yeniden kurulumdur. Bu da ancak çalışan commit değerini bildiğinizde işe yarar. Sabitlenmiş README dosyası Rakazo'yu beta olarak tanımlar, bu yüzden bu hassasiyeti göstermek küçük bir çaba karşılığında büyük fayda sağlar. Kasıtlı sürüm geçmişi olan projeler, openGym gibi daha küçük self-hosted yapılar için önerildiği gibi, yayınlanmış bir tag üzerinde tutulabilir.
Gereksinimler: Node 22, pnpm 9 ve Docker
node -v
pnpm -v
docker --versionpackage.json, "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } ve "packageManager": "pnpm@9.15.0" bildirir. Bu nedenle node -v, v22.22.2 veya sonraki bir 22.x sürümünü, herhangi bir v24 sürümünü ya da v26 ve üzerini yazdırmalıdır. 22.22.2 sürümünden eski bir v22 bu aralığın dışındadır. README'de Node.js 23.x ve 25.x sürümlerinin desteklenmediği açıkça belirtilir. Desteklenen bir Node sürümü NodeSource veya nvm üzerinden kurulmalıdır. Corepack, Node 22 ve 24 ile birlikte gelir. Node 26 ve sonraki sürümlerde önce npm install -g corepack ile kurulmalıdır. Ardından pnpm etkinleştirilmelidir:
corepack enable
corepack prepare pnpm@9.15.0 --activateDocker Engine ve compose eklentisi diğer gereksinimleri karşılar. Self-host dokümanı, bot home volume alt yolları için Docker Engine 26 veya üzerini ve API 1.45 veya üzerini ister. Ayrıca curl ve OpenSSL gerekir. Kullanıcının daemon'a erişebilmesi de gerekir. docker ps, permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock yanıtını veriyorsa kullanıcı docker grubuna eklenmeli ve yeni bir oturum açma kabuğu başlatılmalıdır. Bunun sağladığı yetkiler önce anlaşılmalıdır: docker üyeliği makinede root yetkisine eşdeğerdir. Çünkü bu gruptaki herkes, ana makinenin dosya sistemini bağlayan bir container başlatabilir.
.env dosyasını yapılandırma ve Postgres'i başlatma
cp .env.example .env
chmod 600 .envHerhangi bir işlem başlamadan önce bazı değerlerin değiştirilmesi gerekir. .env.example, BETTER_AUTH_SECRET=replace-with-32-plus-character-secret, ENCRYPTION_KEY=replace-with-64-random-hex-characters, SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret ve SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token değerleriyle birlikte gelir; POSTGRES_PASSWORD ve POSTGRES_APP_PASSWORD ise boş bırakılır. Bu yer tutucuların tümü depoda yayımlandığından bunlardan birini değiştirmeden yapılan bir dağıtım, herkesin okuyabileceği bir sırrı kullanır. Her biri için ayrı bir rastgele değer oluşturun. ENCRYPTION_KEY, tam olarak openssl rand -hex 32 çıktısının ürettiği 64 rastgele onaltılık karakterden oluşmalıdır. Diğer sırlar için 32 veya daha fazla karakter gerekir; bu nedenle base64 satırını her biri için bir kez çalıştırın. İki Postgres parolası için self-host belgesi URL güvenli değerler ister; son satır bu değerleri üretir. Bu satırı da her parola için bir kez çalıştırın. Veritabanında iki oturum açma hesabı vardır. DATABASE_MIGRATION_URL, geçişleri çalıştıran sahip hesabı olan postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo değeriyle gelir. DATABASE_URL ise uygulamanın kendi hesabı olan postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo değeriyle gelir; bu hesabın superuser yetkileri yoktur ve satır düzeyinde güvenlik uygulanır. Her parolayı kendi URL'sine yazın. pnpm db:migrate, belirlediğiniz parolayla rakazo_app hesabını oluşturur.
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24Ardından veritabanını tek başına başlatın ve geçişleri çalıştırın.
docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:buildpnpm sandbox:build, package.json içinde docker build -t rakazo/computer:local infra/sandboxes/computer olarak tanımlanan bot bilgisayar imajını oluşturur. Bu grafiksel bir imajdır; ilk derleme çok sayıda bileşen indirir ve zaman alır. İmajın oluşturulduğunu docker image ls rakazo/computer ile doğrulayın; bu komut tek satır yazdırmalıdır.
Temel compose dosyası hiçbir Postgres portunu yayımlamaz. Bu komuttaki docker-compose.postgres-host.yml overlay'i portu 127.0.0.1:5433 olarak yayımlar; bu adres yalnızca loopback üzerinden erişilebilir olduğundan pnpm db:migrate ve pnpm dev gibi host tarafındaki araçlar bu porta bağlanabilir. Bu ayarı değiştirmeyin. Compose, .env içinde POSTGRES_PASSWORD olmadan Postgres'i başlatmaz. Ancak internetten erişilebilen bir Postgres portu parola saldırılarına davetiye çıkarır. Production compose dosyası da aynı değişkeni okur ve hiçbir veritabanı portunu yayımlamaz.
İlk çalıştırma
pnpm devBu komut dört bileşeni başlatır: 3100 numaralı portta API, Graphile Worker, 5173 numaralı portta Vite web uygulaması ve varsayılan olarak 7091 numaralı portta sandbox supervisor. Eğer bu portlar meşgulse, pnpm dev başka bir boş blok seçer ve URL'leri ekrana yazdırır. Varsayılan portlarda uygulama http://127.0.0.1:5173 adresindedir ve bir giriş sayfası görmeniz gerekir.
Bir VPS üzerinde çalışırken makinenin başında değilsinizdir; bu nedenle 5173 numaralı portu dış dünyaya açmamalısınız. Bunun yerine portları kendi makinenizden SSH (secure shell) üzerinden yönlendirin.
ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-serverBu uygulamayı çalıştırma yöntemleri arasındaki farka dikkat edin. pnpm dev, Vite'ı yerel olarak bağlı şekilde ana makinede çalıştırır. Geliştirme ortamına ait compose dosyasındaki web servisi 127.0.0.1:5173:5173 portunu, api servisi ise 127.0.0.1:3100:3100 portunu yalnızca loopback üzerinden yayınlar; bu sayede aynı tünel her ikisi için de çalışır. Üretim dosyasında ise web uygulaması herhangi bir ana makine portu yayınlamaz ve 5173 portunu yalnızca kendi ağındaki container'lara açar. Caddy ise 80 ve 443 numaralı portları yayınlayan tek bileşendir. Bu nedenle, çalışır durumda bırakacağınız her şey için üretim dosyasını ve onun reverse proxy ayarlarını kullanın.
Sunucuda hangi sandbox sağlayıcısı güvenlidir?
Doğru yapılandırılması gereken ayar budur. SANDBOX_PROVIDER içindeki .env varsayılan olarak docker değerindedir ve sabitlenmiş checkout, self-host belgesinde listelenen sağlayıcıların yanı sıra Railway'i de destekler.
dockervarsayılan sağlayıcıdır. Bot bilgisayarları, makinenizde container olarak çalışır. Bu container'larpnpm sandbox:buildtarafından üretilen image'dan oluşturulur ve bir supervisor altında çalıştırılır. Bir workspace içindeki botlar varsayılan olarak tek bir Team Computer'ı paylaşır. Bot, yalnızca Private Computer üzerinde kendisine ait bir container alır. E2B hesabı gerekmez.e2bbot bilgisayarlarını E2B üzerinde çalıştırır veE2B_API_KEYgerektirir.v0.3.5sürümünde factory, anahtar sağlandığında bunu production ortamında kabul eder veNODE_ENVkısıtlaması uygulamaz. Self-host belgesinde bu sağlayıcının public veya multi-user production için uygun olduğu belirtilir. Bunun nedeni, bot bilgisayarlarını API'nizi ve veritabanınızı çalıştıran hosttan ayrı tutmasıdır.daytona,createosveboatdiğer uzak sağlayıcılardır. Her biri kendi anahtarını gerektirir:DAYTONA_API_KEY,CREATEOS_SANDBOX_API_KEYveyaBOAT_API_KEY.railwaybilgisayarları Railway üzerinde çalıştırır.RAILWAY_API_TOKENve API ile worker üzerinde açıkça seçilmiş birRAILWAY_ENVIRONMENT_IDgerektirir. Sandbox'lar için özel bir Railway projesi veya ortamı kullanın.desktop, belgenin ifadesiyle bot komutlarını doğrudan API ve worker hostu üzerinde çalıştırır.v0.3.5sürümünde API ve worker,NODE_ENVdeğeridevelopmentveyatestolmadığı sürece bunu reddeder. Ancak.env.example,NODE_ENV=developmentdeğerini içerir. Bu nedenlepnpm devçalıştıran bir sunucu bunu hâlâ kabul eder. Bunu public veya paylaşımlı bir serviste etkinleştirmeyin.fakeyalnızca doğrulama amacıyla kullanılan bir emülatördür. Runtime değildir.noneürünü herhangi bir computer host olmadan başlatır.
Bunu tam anlamıyla değerlendirin. Desktop mode'da hiçbir izolasyon sınırı yoktur. Bu nedenle bot, API sürecini çalıştıran kullanıcının yetkileriyle shell komutları çalıştırır. Kullanıcının home directory'sine, SSH anahtarlarına, cloud kimlik bilgilerine ve .env bilgilerine erişebilir. Botun okuduğu bir web sayfasındaki metin, sunucunuzda çalıştırılacak bir komuta dönüşebilir. Sunucuda Desktop mode kullanılması, botun kimlik bilgilerinize erişebilmesine yol açar. Bu modu yalnızca başında bulunduğunuz bir makinede kullanın; aksi durumda hiç kullanmayın. Sağlayıcıyı değiştirmek, bu web sayfası yolunun etrafına bir container koyar ancak yolu kapatmaz. Bota kendi SearXNG arama backend'ini vermek ise aynı injection yüzeyini arama tarafında kapsar.
docker, botlarla hostunuz arasında gerçek bir izolasyon sınırı oluşturur. Ancak botların kendi aralarında oluşturduğu sınır zayıftır. Varsayılan olarak botlar tek bir Team Computer'ı paylaşır. Computer runtime belgesinde, Team botlarının OS kullanıcısını, workspace'i, browser profillerini, shell erişimini ve X11 erişimini paylaştığı belirtilir. Bot başına oluşturulan klasörler çalışmayı düzenler, ancak güvenlik sınırı değildir. Bu nedenle herhangi bir Team botu, başka bir Team botunun dosyalarını okuyabilir. Kendi izolasyonuna ihtiyaç duyan bir bot Private Computer üzerinde çalıştırılmalıdır. Docker provider bunu, kendi ağına sahip ayrı bir kardeş container olarak çalıştırır. Ancak bu container'ları oluşturan supervisor, /var/run/docker.sock yolunu mount eder. Self-host belgesi bunu açıkça belirtir: Bu socket'e erişim, Docker hostunun kontrolüne eşdeğerdir. Bu nedenle supervisor'ı private tutun. .env.example, SANDBOX_SUPERVISOR_TOKEN değerini BETTER_AUTH_SECRET değerinden ayrı, özel bir credential olarak ele alır. Docker sandbox'ları local development dışında çalışırken bu credential'ı gerektirir. Ürün, GitHub üzerinde herkesin okuyabileceği bir placeholder ile gelir. Bunun yerine kendisine ait rastgele bir değer verin. Burada mümkün olan en güçlü ayrım için e2b kullanın. Alternatif olarak Rakazo'ya başka hiçbir şey barındırmayan bir makine tahsis edin. Coding agent'larını geçici bir VM içinde çalıştırmanın arkasındaki gerekçe de aynıdır: Bir agent'ın hata yapmasına karşı en düşük maliyetli önlem, kullandığı makinenin hiçbir değer taşımamasıdır.
Model API anahtarları nereye konur?
Rakazo'nun isteğe bağlı model kredisi faturalandırması, her iki Stripe gizli bilgisi ayarlanmadığı sürece devre dışı kalır. Anahtarı sizin sağlamanız gerekir. .env.example, PI_DEFAULT_PROVIDER=openrouter değerini ayarlar. Bu nedenle OPENROUTER_API_KEY genellikle kullanılan yerdir ve sağlayıcı anahtarları da aynı ayar üzerinden çalışır.
Anahtarı .env içinde tutun ve commit ettiğiniz dosyalara koymayın. Depodaki her iki compose komutu da --env-file .env değerini aktarır. Böylece değerler, git tarafından izlenen YAML dosyalarına hiç yazılmadan container'lara ulaşır. OPENROUTER_API_KEY değerini boş bırakıp kayıt işleminden sonra uygulamada bir model de bağlayabilirsiniz. Bu, ENCRYPTION_KEY değerinin dağıtımla birlikte gelen placeholder yerine gerçek ve rastgele bir değer olmasının bir başka nedenidir.
Bir bot anahtarı kullanmadan önce sağlayıcı tarafında bu anahtar için harcama limiti belirleyin. Döngüye giren bir bot harcama yapmaya devam eder. Rakazo ayrıca MAX_TOOL_CALLS_PER_TURN ayarını sağlar. Bir turun tool-call bütçesini aşması durumunda, son assistant mesajı yine üretilirken turu kontrollü biçimde durdurmak için pozitif bir tamsayı ayarlayın. Ayar tanımsızsa, boşsa veya 0 ise limitsiz kalır. Bu ayar para miktarını değil tool-call sayısını hesaplar. Bu nedenle sağlayıcının harcama limitinin yerine geçmez. Bu anahtara yalnızca bu amaç için kullanılan ayrı bir ad verin. Böylece anahtarı tek başına iptal edebilirsiniz. Bu kurulumu kendiniz için değil de bir ekip için yapıyorsanız, OneCLI ile herkesin agent'ının önüne tek bir gateway koymak aynı soruna farklı bir çözüm sunar. Sağlayıcı anahtarlarını kişi başına birer tane yerine tek bir yerde tutar.
Geliştirme modundan sürekli çalışır durumda bırakılabilecek yapıya geçiş
Repository, Postgres, API, worker, web uygulaması ve otomatik aldığı TLS (transport layer security) sertifikaları için Caddy çalıştıran bir production Compose dosyası içerir. Port yayımlayan tek servis Caddy'dir. Bot bilgisayarları için varsayılan olarak E2B kullanılır. İsteğe bağlı infra/compose/docker-compose.prod.docker.yml overlay'i bunun yerine aynı stack üzerinde yerel Docker bilgisayarlarını çalıştırır. Doküman, bunun eklediği supervisor'ın host üzerinde root ile eşdeğer yetkilere sahip olduğu konusunda uyarır.
sudo --preserve-env=SSH_CONNECTION DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
up -d --wait --pull never
curl --fail https://app.example.com/healthScript'i çalıştırmadan önce yalnızca key ile kullanılabilen bir deploy hesabı oluşturun ve bu hesapla giriş yapabildiğinizi doğrulayın. harden-host.sh, SSH parolasını ve root ile giriş yapılmasını devre dışı bırakır, SSH isteklerine rate limit uygular, mevcut özel ağ kurallarını koruyarak UFW (uncomplicated firewall) üzerinden SSH, HTTP ve HTTPS izinleri ekler ve fail2ban, unattended security updates, AppArmor ile audit kurallarını etkinleştirir. SSH_CONNECTION olmadan çalışmayı reddeder. Bu nedenle komut, değeri sudo üzerinden iletir. Ayrıca üç dakika içinde yeni bir SSH oturumundan onaylamazsanız firewall değişikliğini geri alır. Çalıştırmadan önce okuyun; çünkü giriş yapma biçiminizi değiştirir ve SSH'yi yeniden yükler. Yeni bir SSH girişi başarılı olana kadar sağlayıcınızın konsolunu açık tutun.
Production .env, development sürümünden daha fazlasını gerektirir. Self-host dokümanı, secret'larla birlikte aşağıdaki minimum gereksinimleri listeler.
NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
POSTGRES_APP_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>İlk up işleminden önce sunucuya yönlenen bir A kaydı oluşturun. Caddy, RAKAZO_HOST içindeki ad için sertifika ister. Bu adın bu sunucuya çözülmesi gerekir. Ayrıca HTTP doğrulaması için 80 numaralı portun veya TLS-ALPN doğrulaması için 443 numaralı portun dışarıdan erişilebilir olması gerekir. Her iki challenge da varsayılan olarak etkindir. Bu nedenle yalnızca 80 numaralı portu kapatmak, 443 numaralı port üzerinden sertifika alınmasını engellemez.
SIGNUP_ALLOWLIST değerini başlangıçtan itibaren kendi adresiniz olarak ayarlayın. .env.example, SIGNUPS_ENABLED=true değerini sağlar. Her iki ayar da her API başlangıcında environment üzerinden okunur. Bu nedenle public bir ad üzerinde signup etkin ve allowlist boşsa, sunucunuzu bulan herkes kayıt olabilir. Boş olmayan allowlist her başlangıçta uygulanır ve kaydedilmiş listenin yerini alır. Allowlist ile sınırlandırılmış signup işlemi, ilk hesap dahil olmak üzere mailbox doğrulaması gerektirir. Bu nedenle kayıt olmadan önce e-posta gönderimini yapılandırın. E-posta olmadan kullanılacak yol, dokümana göre SIGNUPS_ENABLED=false ile başlamak ve verdiği server-side bootstrap komutuyla hesabınızı oluşturmaktır. Bu komut, server yetkileri olmayan normal ve doğrulanmış bir hesap oluşturur. Önce allowlist kullanın. İsterseniz daha sonra kısıtlamayı azaltın. Aynı sunucuda birden fazla servis çalıştırıyor ve uygulama başına ayrı bir allowlist yerine tek bir kişi listesi kullanmak istiyorsanız, önlerine bir Authentik instance yerleştirmek bu kararı proxy katmanına taşır. Ancak bu yapı, Rakazo'nun kendi Better Auth hesaplarının önüne geçer; onların yerini almaz.
Production ayarları için repository içindeki docs/self-host.md dosyasını yetkili kaynak olarak kabul edin. Bu dosya kodla birlikte değişir, ancak bu kılavuz değişmez. Compose işlemleri yürüttüğü için standart kurallar geçerlidir. Bir VPS için Docker Compose temelleri, stack'i aylarca müdahale etmeden bırakacağınız durumlarda --env-file ve named volume'ların neden daha önemli olduğunu açıklar.
Yedekler
Bu kurulumda instance verileri Postgres ve data/ dizininde tutulur. Kurtarma için ENCRYPTION_KEY ve yapılandırılmış içerik anahtarlarının da bulunması gerekir. Bu nedenle sunucu dışında kopyalarını saklayın.
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh, Postgres dökümünü alır ve data/ arşivini oluşturur. restore.sh, geliştirme Compose yığınında, uygulama servisleri durdurulmuşken boş bir veritabanı üzerinde çalışır ve production yedek dosyalarını okumaz. Güvenilen bir makine için infra/compose/backup-prod.sh, deponun sağladığı zamanlayıcıyla birlikte /usr/local/sbin/rakazo-backup olarak kurun. Bu araç, /var/backups/rakazo konumuna doğrulanmış bir döküm ve uygulama verilerinin arşivini yazar. Varsayılan olarak en fazla üç doğrulanmış anlık görüntü tutar. Bu sınır RAKAZO_BACKUP_KEEP ile belirlenir. Toplam boyut sınırı RAKAZO_BACKUP_MAX_GB ile 50 GiB olarak belirlenir. Her çalışmadan önce tamamlanmamış anlık görüntüleri ve fazla geçmişi temizler. Böylece döndürme işlemi otomatik olarak yapılır. Ayrıca her yedeği /etc/rakazo/backup.env içinde listelediğiniz genel alıcılarla age kullanarak şifreleyebilir. Böylece sunucu okuyamayacağı yedekler oluşturur. Bu anahtar çiftini denetiminizdeki bir makinede üretin ve özel anahtarı sunucuda tutmayın. Alıcı belirtilmezse yedek düz metin olarak kalır ve günlüklerde bir uyarı yazılır. Ancak ilk şifrelenmiş yedekten sonra, alıcı belirtilmeden yapılan çalıştırma başarısız olur. Düz metne açıkça izin vermek için RAKAZO_BACKUP_ALLOW_PLAINTEXT=1 kullanılmalıdır. Veritabanıyla aynı diskte duran bir yedek, yedek sayılmaz. Bu nedenle yedeği sunucu dışına kopyalayın. Ardından ihtiyaç duymadan önce yedeği yedek bir sunucuda bir kez geri yükleyin.
Neden başarısız olur ve ne görülür
pnpm db:migrate veritabanına erişemiyor. Migration, 127.0.0.1:5433 üzerindeki veritabanı sunucusuna erişemediğini bildirir. Postgres container'ı çalışmıyor olabilir, çalışıyor ancak henüz hazır olmayabilir veya 5433 numaralı portu host'a açan docker-compose.postgres-host.yml overlay'i olmadan başlatılmış olabilir. docker compose --env-file .env -f infra/compose/docker-compose.yml ps komutunu çalıştırın ve postgres servisinin healthy durumunu bildirdiğini kontrol edin. Compose dosyasında her üç saniyede bir çalışan bir health check tanımlıdır. Container sürekli yeniden başlatılıyorsa günlüklerini okuyun. Sabitlenmiş Compose stack'i, Postgres 16'daki eski bir volume Postgres 18'e geçirilene kadar başlatmayı reddeder. docker compose ... down -v bunu temizler ve verileri de siler.
Port zaten kullanılıyor. Başka bir süreç 5433 numaralı portu kullanıyorsa Postgres başlatılırken bind: address already in use hatası alınır. En yaygın neden, durdurulması unutulmuş eski bir Rakazo stack'idir. sudo ss -lntp | grep 5433 komutu işlemi gösterir. Overlay, host portunu POSTGRES_HOST_PORT üzerinden okur. Bu nedenle DATABASE_URL ve DATABASE_MIGRATION_URL değerlerini de birlikte değiştirmek koşuluyla portu değiştirebilirsiniz.
Bir bot hiçbir zaman bilgisayar alamıyor. SANDBOX_PROVIDER=docker mevcutsa ve rakazo/computer:local image'i yoksa başlatılacak bir şey bulunmaz. docker image ls rakazo/computer komutu bu durumu tek satırda gösterir, pnpm sandbox:build ise düzeltir. Supervisor Docker socket'ine erişemiyorsa container da oluşturamaz. Hata iletisinde yol belirtilir: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.
Uzun bir komut yarıda sonlanıyor. .env.example, SANDBOX_COMMAND_TIMEOUT_MS=300000 değerini ayarlar. Bu nedenle bir botun bilgisayarı içindeki tek bir komut beş dakika sonra sonlandırılır. Sandbox'ın çöktüğünü varsaymak yerine yavaş build işlemleri için bu süreyi artırın.
pnpm install karmaşık biçimlerde bozuluyor. Önce node -v değerini kontrol edin. Workspace, ^22.22.2 || ^24.0.0 || >=26.0.0 tanımlar. Bu nedenle 23.x, 25.x ve 22.22.2 öncesindeki tüm 22.x sürümleri bu aralığın dışındadır. Sabitlenmiş .npmrc, engine-strict=true değerini ayarlar. Bu nedenle pnpm install, uygulamanın bağımlılık kodu çalışmadan önce desteklenmeyen Node sürümünü engine/version hatasıyla reddeder.
Oturum açma yerel olarak çalışıyor ancak alan adı üzerinden çalışmıyor. BETTER_AUTH_URL, WEB_ORIGIN ve API_URL değerlerinin tümü, scheme dahil olmak üzere adres çubuğundaki adresle aynı public origin değerini taşımalıdır. Bunlardan birinde kalan eski bir http://127.0.0.1:5173, oturumun kalıcı olmamasının yaygın nedenidir.
Güncellenmiş sabitlenmiş checkout
Checkout'tan oluşturulmuş production Compose stack'i için self-host dokümanındaki yükseltme yolu kısadır: yeni kaynak kodunu çekin, ardından API'yi, worker'ı ve web uygulamasını yeniden build edip yeniden başlatın. Migration işlemleri API başladığında çalışır; başlangıç komutu, API istekleri karşılamaya başlamadan önce migration'ları uygular.
sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
up -d --wait --pull never --build api worker webÖnce yedek alın. Migration'lar ileri yönde ilerler ve beta sürümünde güvenebileceğiniz bir geri dönüş yolu yoktur. Checkout'unuz 30 August 2026 tarihinden eskiyse; buna v0.1.0-beta commit'ini içeren checkout'lar da dahildir; yükseltmeden önce dokümanın 20260830200000_space_scope_names_and_user_credentials migration'ı hakkındaki notunu okuyun. Bu, koordineli bir geçiştir. Bu nedenle önce eski API'yi ve worker'ı durdurun, ardından dokümanda verilen Space gizlilik sınırı kontrolünü çalıştırın. Ayrı uygulama oturum açma özelliğinden önceki bir checkout'tan yükseltme yapıyorsanız yeniden build işleminden önce .env içinde POSTGRES_APP_PASSWORD değerini ayarlayın; production Compose dosyası bu değer olmadan başlatmayı reddeder. Kaynak checkout'u ve production Compose dosyaları ayrıca Postgres 18 çalıştırır. Mevcut bir Postgres 16 kurulumu, yeni düzende başlatılabilmeden önce dokümandaki infra/compose/upgrade-postgres.sh prosedürünün uygulanmasını gerektirir. Sabitlenmiş SHA ile yeni SHA arasındaki commit'leri uygulamadan önce okuyun. Proje bu kadar yeni olduğundan environment değişkenlerini duyuru yapmadan yeniden adlandırabilir ve eksik bir değişken, servisin başlayıp ardından çıkmasına neden olabilir. Rakazo'nun çalıştırılması gereken doğru araç olup olmadığına hâlâ karar veriyorsanız self-host edilen AI agent'ların özeti, bu kategoride başka nelerin bulunduğunu ve her birini çalışır durumda tutmanın maliyetini açıklar.
FAQ
Rakazo'yu 1 GB RAM'e sahip bir VPS üzerinde çalıştırabilir miyim?
Hayır. Postgres, API, worker, sandbox supervisor ve web uygulaması aynı anda çalışır. SANDBOX_PROVIDER=docker ile botların bilgisayarı, her aktif bot için ayrı bir X ekranı ve Chrome süreci içeren grafiksel bir masaüstü barındıran bir container ekler. Tüm bunlar varsayılan olarak 2 GB bellek ve iki CPU sınırı içindedir. v0.3.5 adresindeki self-host belgesi bir sunucu boyutu belirtmez. Kontrol düzlemi için 4 GB RAM'i taban kabul edin; masaüstü uygulamaları kendi makinenizde çalıştırıyorsanız bu değeri daha da artırın.
Masaüstü sandbox sağlayıcısı sunucuda güvenli midir?
Hayır. Self-host belgesi, desktop bileşeninin komutları doğrudan API ve worker ana makinesinde çalıştırdığını belirtir. Bu durumda bot, süreci çalıştıran kullanıcı yetkileriyle hareket eder ve o kullanıcının dosyalarına ve kimlik bilgilerine erişebilir. v0.3.5 adresinde API ve worker, geliştirme ve test modu dışındaki durumlarda bunu reddeder; ancak pnpm dev ile çalışan bir sunucu geliştirme modundadır ve bu isteği kabul eder. Bunu halka açık veya paylaşımlı sunucularda kullanmayın. Bir botun çalışma alanındaki diğer botlarla dosya paylaşmaması gerektiğinde Private Computer sağlayan docker seçeneğini veya birden fazla kişi giriş yaptığında e2b seçeneğini kullanın.
Rakazo'nun hangi sürümünü kurmalıyım?
9 Kasım 2026 itibarıyla en yeni sürüm, 4 Kasım 2026 tarihinde yayınlanan ve Latest olarak işaretlenen v0.8.0 sürümüdür. Bu kılavuzu takip etmek için main veya Ağustos ayındaki v0.1.0-beta ön sürümü yerine, sabitlenmiş v0.3.5 commit değerini, yani f31e3c0699f086d663637c4107858c238a086fb3 commit'ini kullanın. Bir branch değişebilir ve bir tag yeniden işaretlenebilir; bu nedenle ikisi de geri dönebileceğiniz bir ağacı tanımlamaz. Commit değerini kaydedin, çünkü geri alma işlemi yalnızca çalışan sürümü bildiğinizde mümkündür.
OpenRouter API anahtarımı nereye girmeliyim?
.env dosyasında OPENROUTER_API_KEY değişkeni olarak girin; asla commit ettiğiniz bir compose dosyasına yazmayın. Depodaki her iki compose komutu da --env-file .env değişkenini aktarır, böylece değer takip edilen YAML dosyalarına yazılmadan container'lara ulaşır. Ayrıca bu alanı boş bırakıp, giriş yaptıktan sonra uygulama içinden bir model bağlayabilirsiniz. Sağlayıcı tarafında bir harcama limiti belirleyin, çünkü döngüye giren bir bot, siz durdurana kadar modeli çağırmaya devam eder.
Alan adına ve TLS'ye ihtiyacım var mı?
İlk test aşamasından sonraki her şey için evet. Üretim compose dosyası Caddy'yi çalıştırır ve sertifikaları otomatik olarak alır; RAKAZO_HOST değerini genel alan adınıza, BETTER_AUTH_URL, WEB_ORIGIN ve API_URL değerlerini ise aynı genel HTTPS kaynağına ayarlayın. İlk inceleme için alan adını atlayabilirsiniz: pnpm dev komutunu çalıştırın ve 5173 numaralı portu yayınlamak yerine SSH üzerinden yönlendirin.