SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor · Güncellendi 2026-10-23

SandBase Harness kendi sunucunuzda nasıl kurulur?

SandBase Harness v0.3.8 kurulumu ile kendi VPS sunucunuzda agent runtime barındırın. YAML yapılandırması, MCP sunucuları ve Anthropic SDK baseURL ayarları hakkında detaylı rehber.

SandBase agent runtime'ı kendi sunucunuzda barındırdığınızda elde ettikleriniz

SandBase agent runtime'ı kendi sunucunuzda barındırmak, SandBase Harness'ı sahip olduğunuz bir sunucuda çalıştırmak anlamına gelir; böylece oturumlar, kimlik bilgileri, bellek ve denetim izleri başkasının sunucusu yerine sizin diskinizde tutulur. Bu bir Node servisidir. 127.0.0.1:3000 portunu dinler, bir /v1 HTTP API'si ve web konsolu sunar ve durumunu agent dosyalarınızın yanındaki SQLite veritabanında saklar.

/v1 API'si, barındırılan yönetilen agent API'si olan Claude Managed Agents (CMA) yapısına göre tasarlanmıştır. Bu çalışma zamanını her iki yönde de ilginç kılan özellik budur: Anthropic SDK ile kod yazıp baseURL adresini kendi sunucunuza yönlendirebilir, ardından aynı kodu daha sonra barındırılan bir dağıtıma taşıyabilirsiniz.

SandBase Harness bir model ile birlikte gelmez. Bir modeli çağırır. 12 Ekim 2026 itibarıyla OpenAI, Anthropic, MiniMax ve OpenAI uyumlu uç noktaları destekler; bu da kendi kendine barındırılan ağ geçitlerini ve DeepSeek V4 gibi sağlayıcıları kapsar. MiniMax, v0.3.3 sürümünde küresel veya Çin ana kara uç noktası seçeneğiyle birinci sınıf bir sağlayıcı olarak eklenmiştir. API anahtarınızı veya OpenAI API'si ile konuşan yerel bir sunucuyu yine sizin sağlamanız gerekir.

Başlamadan önce gerekenler

  • En az 2 GB RAM kapasitesine sahip, Ubuntu 24.04 yüklü bir VPS. TypeScript derleme süreci, kurulumun en yoğun kaynak tüketen adımıdır.
  • Node.js 22 veya daha yeni bir sürüm ile npm 10 veya daha yeni bir sürüm. Her ikisi de proje tarafından belirtilen kesin minimum gereksinimlerdir.
  • git ve kullanmayı planladığınız model sağlayıcısına ait bir API anahtarı.
  • Yalnızca oturum bazlı container korumalı alanları (sandbox) kullanmak istiyorsanız Docker.

Ubuntu 24.04, kendi deposunda Node 18.19 sürümünü sunmaktadır; bu sürüm minimum gereksinimin altında kaldığı için Node kurulumunu NodeSource üzerinden gerçekleştirin.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -v

node -v komutu v22 veya daha yüksek bir sürüm, npm -v komutu ise 10 veya daha yüksek bir sürüm çıktısı vermelidir. Eğer node -v komutu hala v18.19.1 çıktısını veriyorsa, dağıtım paketi hala yüklüdür ve PATH üzerinde önceliklidir. Devam etmeden önce bu paketi kaldırın; çünkü derleme işlemi, shell tarafından bulunan ilk node sürümü ile çalıştırılır.

SandBase yazılımını v0.3.8 etiketi ile kurun

Kurulumu hareketli bir daldan değil, her zaman bir etiket üzerinden gerçekleştirin. main ile yapılan çıplak bir klonlama, bir saat önce eklenen kodları getirebilir ve aşağıdaki yapılandırma anahtarları bu kodlarla uyumlu olmayabilir. 30 Ağustos 2026 tarihinde yayınlanan v0.3.8, 12 Ekim 2026 itibarıyla güncel etikettir ve projenin kendi kurulum dokümanında referans alınan etikettir.

sudo install -d -o "$USER" -g "$USER" /opt/sandbase
cd /opt/sandbase
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build

npm install yerine npm ci kullanın. ci, commit edilmiş kilit dosyasında (lockfile) kayıtlı olan tam sürümleri kurar; böylece dizininiz, geliştiricilerin test ettiği dizin ile birebir aynı olur. npm install ise daha yeni sürümleri çözümleyebilir; sabitlenmiş bir etiketin sessizce sabitlenmiş olmaktan çıkmasının nedeni budur.

Şimdi bir çalışma alanı oluşturun. Çalışma alanı, aracı dosyalarınızı ve tüm çalışma zamanı durumunu tutan ayrı bir dizindir. Bu alanı kaynak kod dizininin dışında tutmak, verilerinize dokunmadan daha yeni bir etiketi çekebilmenizi sağlar.

mkdir -p /opt/sandbase/workspace
cd /opt/sandbase/workspace
node /opt/sandbase/sandbase-harness/dist/index.js init
node /opt/sandbase/sandbase-harness/dist/index.js start

init, çalışma alanı içerisine bir .managed-agents/ dizini yazar. start, konsolu http://127.0.0.1:3000/dashboard adresinde, API'yi ise http://127.0.0.1:3000/v1 adresinde ayağa kaldırır. Her ikisine de henüz dizüstü bilgisayarınızdan erişilemez; bu beklenen bir durumdur ve ilerleyen bölümlerde ele alınacaktır. Şimdilik konsola SSH üzerinden erişin:

ssh -N -L 3000:127.0.0.1:3000 you@your-server

O uzun node .../dist/index.js yolu yazmak yorucu olacağından, ona bir isim verin.

alias sandbase='node /opt/sandbase/sandbase-harness/dist/index.js'

Aşağıdaki komutlar bu temel üzerine sandbase <command> olarak yazılmıştır.

npm üzerinden kurmayın

Proje, kendi kurulum dokümanında şunu belirtmektedir: npm üzerinde görünen kapsam dışı (unscoped) managed-agents paketi bu projeye ait değildir. Bu nedenle npx managed-agents ve npm install -g managed-agents komutları, hedeflediğiniz çalışma zamanı ile ilgisi olmayan bir paket indirir. Bakımcılar resmi ve kapsamlı (scoped) bir paket duyurana kadar kurulumu etiketli GitHub kaynağından yapın. Bu durum projenin geçmişinde küçük bir dipnot değildir: v0.3.1 sürümü, esas olarak eski npm hızlı başlangıç yöntemini sabitlenmiş etiketli kaynak yolu ile değiştirmek için yayınlanmıştır.

Çalışma alanını bir model sağlayıcısına yönlendirme

init, .managed-agents/config.yaml yazar. Tüm çalışma alanı için tek bir sağlayıcı yapılandırılır ve ardından bireysel aracılar somut model kimliklerini seçer.

model:
  provider: openai
  api_key: ${OPENAI_API_KEY}
storage:
  metadata:
    provider: sqlite
    options: {}
  artifacts:
    provider: local
    options:
      base_path: files

${OPENAI_API_KEY} formu, değeri işlem ortamından alır; bu sayede anahtar, yapılandırma dosyasının ve bu dosyanın aldığınız her yedeğinin dışında kalır. systemd, ayrıcalıkları düşürmeden önce EnvironmentFile= dosyasını root olarak okuduğu için, bu anahtarı yalnızca root kullanıcısının okuyabileceği bir ortam dosyasına yerleştirin.

sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.env

Bu dosyayı bir düzenleyicide açın ve OPENAI_API_KEY=sk-... satırını ekleyin. Sağlayıcı anahtarları buraya aittir. Bir aracının oturum sırasında kullandığı gizli veriler ise bunun yerine çalışma zamanının kimlik bilgisi kasalarına aittir; bu, farklı bir etki alanına sahip farklı bir sorundur ve herhangi bir yere üretim ortamı belirteci (token) yapıştırmadan önce yapay zeka aracılarından gizli verileri uzak tutma konusunu okumak faydalıdır.

Agent YAML dosyası: mcp_servers, araçlar ve izin politikaları

Agent'lar, çalışma alanı agents/ dizinindeki YAML dosyaları olarak tanımlanır. Burası, runtime'ın aslında en çok vakit geçireceğiniz kısmıdır. Küçük bir agent döngüsünü elle yazdıktan sonra anahtarlar daha anlaşılır hale gelir; çünkü her biri, aksi takdirde bizzat kodlamanız gerekecek bir mekanizmanın (sistem istemi, araç listesi ve bir araç tetiklenmeden önce çalışan denetim) ayar düğmesidir.

name: Incident commander
description: Triages alerts and coordinates response.
model: gpt-4o
system: |-
  You are an on-call incident commander.
mcp_servers:
  - name: sentry
    type: url
    url: https://mcp.sentry.dev/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy: { type: always_ask }
    configs:
      - name: bash
        permission_policy: { type: always_ask }
  - type: mcp_toolset
    mcp_server_name: sentry
metadata:
  template: incident-commander

Dosyayı yükleyin ve sisteme işlendiğini doğrulayın:

sandbase reload
sandbase list
sandbase chat agent_assistant --message "hello"

reload, seed YAML dosyasını SQLite içine aktarır. list komutu artık agent'ı bir ID ile listelemelidir. Eğer list çıktısında görünmüyorsa dosya ayrıştırılamamıştır; hatanın nedeni .managed-agents/logs/runtime.log dosyasında yazılıdır.

mcp_servers MCP (model context protocol) uç noktalarını tanımlar. type: url, çalışma zamanının başka bir yerde çalışan bir sunucuyla HTTP üzerinden iletişim kurduğu anlamına gelir; bu nedenle hâlihazırda işlettiğiniz her şey burada da kullanılabilir. Buna, çalışma zamanıyla aynı VPS üzerinde barındırılan MCP sunucuları da dahildir. Web araması genellikle başvurulan ilk araçtır. Ancak bir aracı yapılandırmadan önce kendi SearXNG örneğinizi bir ajana sunma konusunu okumanız gerekir. Çünkü yabancılar tarafından yazılmış sayfaları döndüren bir araç, güvenilmeyen metni doğrudan modelin bağlamına yerleştirir. İlk yapılandırma için daha kontrollü yaklaşım bunun tersidir: zaten sahip olduğunuz verilere salt okunur erişim sağlayan bir uç nokta kullanılır. openGym bunu antrenman takip uygulamasının yanında sunar. Böylece ajan, antrenman geçmişinizle ilgili soruları yanıtlayabilir; ancak bu verileri değiştiremez.

Bir sunucuyu bildirmek, araçlarını otomatik olarak agent'a vermez. tools listesi, mcp_server_name değeri yukarıdaki name ile eşleşen bir mcp_toolset girdisi aracılığıyla bunu sağlar. Eğer agent, MCP araçları yokmuş gibi davranıyorsa, başka bir yere bakmadan önce bu iki dizgeyi karakter karakter karşılaştırın.

agent_toolset_20260401, yerleşik araç setidir. Sondaki tarihli sonek bir şema sürümüdür; bu sürüme sabitlenmiş bir agent, yazıldığı dönemdeki araç tanımlarını korur. default_config, setteki her araç için politikayı belirler; configs altındaki her girdi ise, örnekteki bash gibi, belirli bir aracı ismen geçersiz kılar.

permission_policy, bir runtime'ın ham bir model çağrısına kıyasla değer kazandığı yerdir. always_ask, oturumu duraklatır ve çağrı çalıştırılmadan önce bir insanın onayını bekler. always_allow ise çağrıya izin verir. bash değerini always_ask olarak ayarlamak, agent'ın siz tam komutu görmeden bir shell komutu çalıştıramayacağı anlamına gelir; bu, Claude Code'u bir VPS üzerinde güvenli bir şekilde çalıştırırken başvuracağınız kontrol mekanizmasıyla aynıdır. Eğer DeepSeek Harness da kullanıyorsanız, aynı kontroller oraya YAML anahtarları yerine eklentiler olarak gelir ve bütçeleri sınırlayan ve araç çağrılarını denetleyen eklentiler, bu bloğun en yakın karşılığıdır.

Dört sandbox modu ve kullanım alanları

Kod çalıştıran araç çağrıları bir sandbox içerisinde yürütülür. Backend seçimi, ortamın config nesnesi içindeki sandbox_provider üzerinden veya konsolda Ayarlar altındaki Sandbox düzenleyicisinde Gelişmiş sekmesinden varsayılan çalışma alanı ayarı olarak yapılır. Ortamlar, POST /v1/environments adresindeki API üzerinden oluşturulur.

local, kodu çalışma zamanının bir alt süreci olarak, ana makinede ve çalışma zamanının kendi kullanıcısı yetkileriyle çalıştırır. Bir ortamda backend belirtilmediğinde varsayılan olarak kullanılır; yalnızca sizin kullanıcı olduğunuz ve ajanın sadece size ait dosyaları okuduğu durumlarda uygundur. Çalışma zamanının yükleyemediği bir backend belirten ortamlar, sessizce burada çalıştırılmak yerine reddedilir. Bu bir izolasyon yöntemi değildir. Dosyaları silen bir araç çağrısı sizin dosyalarınızı siler; /etc/sandbase/runtime.env dosyasını okuyan bir araç çağrısı ise sağlayıcı anahtarınızı okur.

docker, her oturum için bir container başlatır.

{
  "sandbox_provider": "docker",
  "image": "node:22-slim",
  "resources": { "memory": "1g", "cpu": 1 }
}

Oturum kendi dosya sistemine sahip olur ve container oturum sonunda kaldırılır. Bellek ve CPU sınırları bu modun doğal bir parçası değildir: çalışma zamanı, resources bloğu örnekteki gibi ayarlandığında container'a --memory ve --cpus parametrelerini ekler. Bu bloğun olmadığı bir ortamda, container herhangi bir üst sınır olmadan çalışır. image parametresini boş bırakırsanız, çalışma zamanı ghcr.io/sandbaseai/sandbase-harness-sandbox:latest değerini kullanır. Bir ajan sizin yazmadığınız bir kodu çalıştırdığı anda bu moda geçiş yapın. Bu yöntemin maliyeti, çalışma zamanı kullanıcısının Docker soketine erişim gerektirmesidir; docker grubuna üyelik, ana makinede root yetkisine eşdeğerdir. Oturum bazlı container'lar, çalıştırma başına bir container içeren self-hosted ajan sandbox'ları ile aynı yapıdadır; dolayısıyla, dışarı sızan bir sürecin nelere erişebileceğine dair mantık burada da aynen geçerlidir.

kubernetes, oturum iş yükünü bir pod olarak çalıştırır ve bunu kubectl exec ile kubectl cp kullanarak yönetir. Çalışma zamanı imajında kubectl bulunmalıdır ve ServiceAccount'unun hedef namespace içinde pod oluşturma, silme, alma, listeleme ve izleme (watch) yetkilerine, ayrıca exec alt kaynağına erişim iznine sahip olması gerekir. Bu mod, yalnızca halihazırda bir cluster yönetiyorsanız kurulum zahmetine değer.

self-hosted worker, Ayarlar'da remote ve Ortam'da self_hosted olarak adlandırılır; araç kodunu bu makinede hiç çalıştırmaz. Çalışma zamanı işi bir kuyruğa ekler; Ayarlar'dan alınan worker API URL'si ve anahtarı ile yapılandırılmış harici bir worker, kuyruktaki öğeleri ana makine dışında alır ve tamamlar. Kodun, sağlayıcı anahtarınızı barındırmayan bir makinede çalışması gerektiğinde uygundur. Kaynak sınırları yalnızca docker ve kubernetes tarafından dikkate alınır; bu nedenle bir worker'ı sınırlandırmak, worker'ın barındığı makinenin sorumluluğundadır.

Runtime neden 127.0.0.1 adresine bağlı?

Çünkü kimlik doğrulama kapalı olarak başlar. Runtime, en az bir API anahtarı mevcut olduğunda bearer-token kimlik doğrulamasını etkinleştirir; yeni bir init kurulumunda ise hiçbir anahtar oluşturulmaz. Varsayılan ayarlarda 0.0.0.0 adresine bağlanmak, kabuk araçlarını ve sağlayıcı anahtarınızı barındıran kimlik doğrulaması yapılmamış bir aracı runtime'ını genel internete açacaktır.

Bu nedenle, erişilebilir olmasını istediğinizde bağlama adresini değiştirmeyin ve şu iki işlemi yapın.

İlk olarak, kimlik doğrulamayı açın. Servis ortam dosyasında MANAGED_AGENTS_API_KEY ayarını yapın veya POST /v1/api-keys ile bir anahtar oluşturun; bu komut bir kez secret_key alanını döndürür ve bir daha göstermez. İstemciler her API isteğinde Authorization: Bearer <key> gönderir veya aynı anahtarı x-api-key olarak kullanır, ancak ikisini asla aynı anda kullanmazlar. Anahtar konsolu değil, API'yi korur: kontrol paneli sayfaları ve statik varlıkları anahtarsız yüklenir; /v1/x/health ve /v1/x/metrics için de aynı durum geçerlidir. Tek bir anahtar, paylaşılan tek bir kimlik anlamına gelir; bu yüzden eğer ekip arkadaşlarınızın her biri için ayrı, sağlayıcı anahtarlarının tek bir ağ geçidinde tutulduğu korumalı bir aracı yapısı istiyorsanız, OneCLI bu yapı için tasarlanmıştır.

İkinci olarak, önüne bir reverse proxy yerleştirin ve TLS (transport layer security) sonlandırmasını orada yapın. Runtime, tasarımı gereği düz HTTP sunar ve sertifika işlemlerini başka bir bileşenin yönetmesini bekler.

server {
    listen 443 ssl;
    server_name agents.example.com;

    ssl_certificate     /etc/letsencrypt/live/agents.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/agents.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Bu satırlardan ikisi süsleme değildir. proxy_buffering off önemlidir çünkü oturumlar server-sent events (SSE) üzerinden akar; tamponlama (buffering) açık olduğunda nginx, yanıtı tampon dolana kadar tutar. Bu durumda aracı çalışırken konsolda hiçbir şey görünmez ve işlem bittiğinde tüm çıktı tek seferde dökülür. proxy_read_timeout 3600s önemlidir çünkü varsayılan değer 60 saniyedir; bu nedenle bir dakikadan uzun süre sessiz kalan bir akış, proxy tarafından işlem ortasında kapatılır ve bu hata, runtime çökmüş gibi görünür.

Güvenlik duvarında 22 ve 443 numaralı portları açın. 3000 numaralı portu kapalı tutun; çünkü proxy ona loopback üzerinden erişir ve sunucu dışındaki hiçbir şeyin erişmemesi gerekir. /v1/x/metrics anahtarsız yanıt verdiği için, runtime metriklerini yayınlamak istemiyorsanız sunucu bloğuna location = /v1/x/metrics { return 404; } ekleyin.

Anthropic SDK'yı kendi sunucunuza yönlendirme

Çalışma zamanı, CMA biçimli bir /v1 yüzeyi uygular; bu nedenle bir Anthropic SDK istemcisi, tek bir alanı değiştirerek onunla iletişim kurar.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
  baseURL: 'http://127.0.0.1:3000'
});

Ayrıca Claude Managed Agents istemcilerinin gönderdiği beta başlıklarını, yani anthropic-beta: managed-agents-2026-04-01 ve anthropic-beta: agent-memory-2026-07-22 başlıklarını da kabul eder. Uyumluluk başlığı içermeyen düz bir istek, yerel bir çağırıcı olarak kabul edilir. x-api-key, anthropic-version veya anthropic-beta içeren bir istek, barındırılan kurallara tabi tutulur: 2023-06-01 sürümü ve managed-agents beta sürümü gereklidir; ancak /v1/memory_stores rotaları agent-memory beta sürümünü gerektirir ve ikisinin bir arada kullanımını reddeder. Bu başlıklar, barındırılan bir dağıtım için yazılan kodun burada hiçbir değişiklik yapılmadan çalışması için mevcuttur.

Uyumluluk tam değil, yakındır. Bir yüzeyin var olduğunu varsaymadan önce checkout içindeki docs/api-matrix.md dosyasını okuyun; proje, istemci tarafındaki özel araçlar da dahil olmak üzere kendi eksikliklerini orada belgeler. Bu araçlar, mevcut olay-sonuç protokolünün üzerinde hala adlandırılmış bir kayıt gerektirir.

Düz HTTP de aynı derecede iyi çalışır ve çalışma zamanının canlı olduğunu kanıtlamanın en hızlı yoludur:

curl -N -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello", "stream": true}'

Sağlıklı bir yanıt, sürekli gelen bir olay akışıdır. Bağlantı koparsa, tüm oturumu yeniden oynatmak yerine gördüğünüz son olaydan devam edin:

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: EVENT_ID"

Bu devam ettirilebilir akış, bir oturumun dizüstü bilgisayar kapandığında bile hayatta kalmasının nedenidir. Olaylar sunucuda kalıcı hale getirilir, bu nedenle istemci tek kopyayı tutmak yerine bir günlüğü yeniden oynatır.

Kimlik bilgileri, bellek ve denetim izlerinin disk üzerinde bulunduğu yer

Çalışma zamanının sahip olduğu her şey çalışma alanındaki .managed-agents/ dizini altındadır.

.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/
  • data.db, SQLite meta verilerini içerir: aracılar, oturumlar, kimlik bilgisi kasası girişleri, bellek deposu girişleri ve API anahtarları.
  • files/ yüklenen dosya baytlarını, skills/ ise yüklenen yetenek paketlerini tutar.
  • snapshots/ oturum çalışma alanı anlık görüntülerini, sandbox/ ise yerel mod oturumlarının çalışma dizinlerini barındırır.
  • logs/runtime.log, bir şey sessizce çalışmadığında bakılması gereken ilk yerdir.

Kimlik bilgisi kasaları, her biri environment_variable gibi bir auth_type ile eklenen ve oturum oluşturulurken vault_ids aracılığıyla oturuma bağlanan gizli bilgiler gruplarıdır. Bellek depoları, kendi erişim ayarı ve talimatlarıyla bir memory_store olarak oturuma bağladığınız adlandırılmış girişleri tutar. Her ikisi de data.db içinde yaşar; bu, ham bir model çağrısı ile bu sistem arasındaki temel farktır: çalışma zamanı oturumlar boyunca hatırlama yapar ve gerçekleşenleri kaydeder.

Tek bir dizin olduğu için, yedeklemeyi bir bütün olarak yapın.

sudo systemctl stop sandbase
sudo tar czf /root/sandbase-$(date +%F).tgz -C /opt/sandbase/workspace .managed-agents
sudo systemctl start sandbase

Önce servisi durdurun. Çalışma zamanı yazma işlemi yaparken bir SQLite veritabanını kopyalamak, geri yükleme sırasında açılmayacak bir dosya oluşturabilir ve bunu ancak ihtiyaç duyduğunuz gün fark edersiniz. Aracı YAML dosyalarını git üzerinde, durumu ise başka bir yerde tutmak isterseniz, dağıtım dokümanı start üzerinde --data-dir ile durum konumunun sabitlenmesini destekler.

Geri yükleme işlemi bunun tersidir: yeni bir sunucuda aynı etiketi kontrol edin, arşivi çalışma alanına açın ve servisi başlatın. ${OPENAI_API_KEY} formunu kullandıysanız sağlayıcı anahtarınız arşivde yer almaz, bu nedenle onu her zaman erişebileceğiniz bir yerde saklayın.

systemd altında çalıştırma

Çalışma zamanına (runtime) özel bir kullanıcı atayın; böylece yerel sandbox modundaki bir araç çağrısı sizin yetkilerinizle işlem yapamaz.

sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbase

Bunu /etc/systemd/system/sandbase.service olarak kaydedin.

[Unit]
Description=SandBase Harness runtime
After=network-online.target

[Service]
User=sandbase
Group=sandbase
WorkingDirectory=/opt/sandbase/workspace
EnvironmentFile=/etc/sandbase/runtime.env
ExecStart=/usr/bin/node /opt/sandbase/sandbase-harness/dist/index.js start --host 127.0.0.1 --port 3000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Projenin kendi dağıtım örneği PATH üzerinde bir managed-agents binary dosyasını çağırır. Etiketli kaynak (tagged-source) kurulumu bunu oluşturmaz, bu nedenle ExecStart, derlenmiş giriş noktasına karşı node komutunu çalıştırır.

sudo systemctl daemon-reload
sudo systemctl enable --now sandbase
sudo systemctl status sandbase
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/dashboard

Sağlıklı bir sonuç, status üzerinden active (running) ve curl üzerinden 200 değeridir. Başka bir sonuç alırsanız, önce journalctl -u sandbase -n 50 dosyasını, ardından .managed-agents/logs/runtime.log dosyasını okuyun. enable --now önemli olan kısımdır, çünkü elle başlatılan bir süreç bir sonraki yeniden başlatmadan sonra kaybolur.

Neler bozulur ve göreceğiniz mesajlar

npm run build, npm'den herhangi bir hata almadan sonlandırılıyor. 1 GB RAM'e sahip bir VPS üzerinde TypeScript derleme işlemi, çekirdeğin bellek yetersizliği (out-of-memory) yöneticisi tarafından durdurulur. Bu durum npm'e değil, doğrudan çekirdek günlüğüne raporlanır. Sonlandırılan node sürecini belirten satırı görüntülemek için journalctl -k | grep -i "out of memory" komutunu kullanarak durumu doğrulayın. Swap alanı ekleyin veya derlemeyi daha büyük bir sunucuda yapıp dist/ dosyasını kopyalayın.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. Başka bir süreç halihazırda ilgili portu kullanıyor. sudo ss -lntp | grep 3000 komutu bu süreci tanımlar. Söz konusu süreci durdurun ya da çalışma zamanını (runtime) --port 3001 ile başlatıp proxy ayarlarını güncelleyin.

Dashboard dizüstü bilgisayarınızdan yüklenmiyor. Bu beklenen bir davranıştır çünkü çalışma zamanı loopback arayüzüne bağlanır. Yukarıda belirtilen SSH tünelini kullanın veya reverse proxy kurulumunu tamamlayın. Bir anahtar oluşturulana kadar kimlik doğrulama kapalı olduğundan, bu durumu --host 0.0.0.0 ile düzeltmeye çalışmayın.

Docker sandbox'lar permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock hatasıyla başarısız oluyor. sandbase kullanıcısı docker grubuna dahil değil. Sorunu sudo usermod -aG docker sandbase ile giderin ve servisi yeniden başlatın. Verdiğiniz yetkinin kapsamını anlayın: bu grup ana makinede root yetkilerine sahiptir, dolayısıyla çalışma zamanına kendi kullanıcısını atama amacınızın bir kısmını geçersiz kılar.

Kubernetes sandbox'lar Error from server (Forbidden) hatasıyla başarısız oluyor. ServiceAccount pod izinlerinden veya exec alt kaynağından yoksun. Durumu doğrudan kubectl auth can-i create pods/exec -n <namespace> ile kontrol edin; bu komut yes veya no yanıtını verecektir.

Bir API anahtarı ekledikten sonra API istekleri 401 hatası döndürüyor. Kimlik doğrulama, ilk anahtar oluşturulduğunda devreye girer. Bu koruma API'yi kapsar ancak konsolu kapsamaz: dashboard sayfaları ve statik varlıkları herkese açık kalmaya devam eder, bu nedenle konsol yüklenir ancak API çağrıları için anahtara ihtiyaç duyar. Authorization: Bearer <key> veya x-api-key: <key> başlıklarından yalnızca birini gönderin; her ikisini birden göndermeyin. Kimlik doğrulama kapalı olsa dahi, her iki başlığı da içeren bir istek 401 hatasıyla reddedilir. Anahtarı kaybettiyseniz yeni bir tane oluşturun; çünkü secret_key yalnızca bir kez gösterilir ve sistemde yalnızca hash değeri olarak saklanır.

Bir MCP sunucusunun araçları oturumda görünmüyor. mcp_servers içindeki name ile tools bloğundaki mcp_server_name değerini karşılaştırın. Ardından çalışma zamanının sunucunun kendisinden curl -i <url> ile ilgili URL'ye erişebildiğini doğrulayın. URL tabanlı bir MCP sunucusu bir ağ bağımlılığıdır; bir VPS, isim çözümleme ve trafik yönlendirme işlemlerini dizüstü bilgisayarınızdan farklı şekilde gerçekleştirir.

FAQ

SandBase Harness'ı OpenAI veya Anthropic anahtarı olmadan çalıştırabilir miyim?

Evet, bir MiniMax anahtarı veya OpenAI uyumlu bir uç nokta ile çalıştırabilirsiniz. Çalışma zamanı (runtime); OpenAI, Anthropic, MiniMax ve OpenAI uyumlu sağlayıcıları destekler; bu nedenle OpenAI API'si ile konuşan yerel bir sunucu iş görür. Çalışma alanı sağlayıcısını .managed-agents/config.yaml içinde ayarlayın ve api_key ile uç noktayı bu sağlayıcıya yönlendirin. Çalışma zamanı kendi içinde bir model barındırmaz, bu yüzden çağrılara yanıt verecek bir kaynağın bulunması gerekir.

Çalışma zamanını herkese açık bir portta yayınlamak güvenli midir?

Varsayılan kurulumuyla güvenli değildir. 127.0.0.1:3000 adresine bağlanır ve kimlik doğrulama kapalı olarak başlar; çözüm, farklı bir bağlantı adresi kullanmak değildir. Bir API anahtarı oluşturun veya MANAGED_AGENTS_API_KEY ayarını yapılandırın; böylece API için taşıyıcı belirteç (bearer-token) kimlik doğrulaması etkinleşir. Ardından TLS için önüne nginx veya Caddy yerleştirin ve 3000 numaralı portu güvenlik duvarında kapalı tutarak içeriye yalnızca proxy üzerinden erişilmesini sağlayın.

Yerel, Docker ve Kubernetes sandbox'ları arasındaki fark nedir?

local, araç kodunu ana makinede çalışma zamanının bir alt süreci olarak, çalışma zamanı kullanıcısının izinleriyle ve herhangi bir izolasyon olmadan çalıştırır. docker, her oturuma kendi konteynerini ve dosya sistemini atar, oturum bittiğinde bunları kaldırır; bellek ve CPU sınırlandırması ise yalnızca ortamın resources bloğunda tanımlanmışsa uygulanır. kubernetes, oturumu bir pod olarak çalıştırır ve kubectl exec ile yönetir; bu da çalışma zamanı imajı içinde kubectl bileşenini, podlar üzerinde RBAC yetkilendirmesini ve hedef ad alanında exec alt kaynağını gerektirir. Dördüncü bir arka uç olan self-hosted worker ise işi harici bir işçiye kuyruklar, böylece kod ana makine dışında çalıştırılır.

Tam olarak neleri yedeklemem gerekiyor?

Çalışma alanındaki .managed-agents/ dizinini yedeklemelisiniz. Bu dizin; config.yaml dosyasını, ajanları, oturumları, kimlik bilgisi kasası girişlerini ve bellek kayıtlarını içeren data.db SQLite veritabanını, ayrıca yüklenen dosyaları, beceri paketlerini ve oturum anlık görüntülerini barındırır. SQLite'ın arşivleme sırasında yazma hatası vermemesi için kopyalama işleminden önce servisi durdurun. ${OPENAI_API_KEY} olarak referans verilen sağlayıcı API anahtarları yedek içinde yer almaz, bu yüzden bunları ayrı bir yerde saklayın.

Neden main yerine v0.3.8 etiketini (tag) klonlamalıyım?

Bir etiket sabit bir ağaç yapısıdır; bu sayede okuduğunuz yapılandırma anahtarları ve CLI komutları, kullandığınız sürümle tam olarak eşleşir. main değişebilir ve bir rehber yazıldıktan sonra siz onu uygulayana kadar bir yapılandırma anahtarının ismi değiştirilmiş olabilir. Proje ayrıca, npm üzerindeki kapsam dışı managed-agents paketinin bu projeye ait olmadığı konusunda uyarıda bulunur; bu nedenle npx managed-agents komutu alakasız bir şey kurabilir. v0.3.1 sürümü, temel olarak o npm hızlı başlangıç yöntemini, sabitlenmiş etiketli kaynak yolu ile değiştirmek için yayınlanmıştır.

Bu yazı işinize yaradı mı?