SandBase agent runtime kendi sunucusunda nasıl kurulur?

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

SandBase agent runtime'ı kendi sunucunuzda barındırmak, SandBase Harness'ı kendi sahip olduğunuz bir sunucuda çalıştırmak anlamına gelir; böylece oturumlar, kimlik bilgileri, bellek ve denetim kayıtları 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, durumunu ise agent dosyalarınızın yanında bir 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 runtime'ı her iki yönde de ilgi çekici kılan şey 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. Ağustos 2026 itibarıyla OpenAI, Anthropic ve OpenAI uyumlu uç noktaları destekler; bu da kendi barındırdığınız ağ geçitlerini ve DeepSeek V4 gibi sağlayıcıları kapsar. Yine de bir API anahtarı veya OpenAI API'si ile konuşan yerel bir sunucu sağlamanız gerekir.

Başlamadan önce gerekenler

• En az 2 GB RAM'e sahip, Ubuntu 24.04 çalıştıran bir VPS. TypeScript derleme süreci, kurulumun en yoğun aşaması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 zorunlu minimum gereksinimlerdir.
• git ve kullanmayı planladığınız model sağlayıcısı için bir API anahtarı.
• Yalnızca oturum bazlı container korumalı alanları (sandbox) kullanmak istiyorsanız Docker.

Ubuntu 24.04, kendi deposunda minimum gereksinimin altında kalan Node 18.19 sürümünü sunar; bu nedenle 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 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'in bulduğu ilk node sürümü ile çalışır.

SandBase uygulamasının v0.3.2 etiketinden kurulması

Kurulumu her zaman bir etiket üzerinden yapın, asla güncellenen bir dal (branch) kullanmayın. main üzerinden yapılan çıplak bir klonlama (bare clone), bir saat önce eklenen kodları getirir ve aşağıdaki yapılandırma anahtarları bu kodlarla uyumlu olmayabilir. 16 Ağustos 2026 itibarıyla güncel etiket v0.3.2 sürümüdür.

sudo install -d -o "$USER" -g "$USER" /opt/sandbase
cd /opt/sandbase
git clone --branch v0.3.2 --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 dizinle birebir aynı olur. npm install ise daha yeni sürümleri çözümlemeye çalışır; bu da sabitlenmiş bir etiketin sessizce sabitlenmiş olmaktan çıkmasına neden olur.

Şimdi bir çalışma alanı (workspace) oluşturun. Çalışma alanı, agent dosyalarınızı ve tüm çalışma zamanı durumunu tutan ayrı bir dizindir. Bu dizini 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. Henüz dizüstü bilgisayarınızdan bunlara 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 yazması zahmetli olduğundan, 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 kurulum yapmayın

Proje, kendi kurulum dokümantasyonunda ş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 bir kapsamlı (scoped) paket duyurana kadar kurulumu etiketli GitHub kaynağından gerçekleştirin. Bu durum, projenin geçmişinde küçük bir dipnot değildir: v0.3.1 sürümü, temel 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 dosyasını yazar. Tüm çalışma alanı için tek bir sağlayıcı yapılandırılır ve ardından bağımsız 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 süreç ortamından alır; böylece anahtar, yapılandırma dosyasının ve bu dosyanın aldığınız tüm yedeklerinin dışında kalır. systemd, ayrıcalıkları düşürmeden önce EnvironmentFile= dosyasını root olarak okuduğundan, 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 bilgiler ise bunun yerine çalışma zamanının kimlik bilgisi kasalarına (credential vaults) aittir; bu, farklı bir etki alanına sahip farklı bir sorundur ve bir üretim ortamı belirtecini (production token) herhangi bir yere yapıştırmadan önce yapay zeka aracılarından gizli bilgileri uzak tutma konusunu okumakta fayda vardır.

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

Ajanlar, çalışma alanı agents/ dizinindeki YAML dosyaları olarak tanımlanır. Burası, çalışma zamanının (runtime) üzerinde en çok vakit geçireceğiniz kısmıdır.

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, başlangıç YAML dosyasını SQLite içine aktarır. list komutu artık ajanı bir kimlik numarasıyla (ID) listelemelidir. Eğer list çıktısında ajan görünmüyorsa dosya ayrıştırılamamıştır; hatanın nedeni .managed-agents/logs/runtime.log dosyasında kayıtlı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 haberleştiği anlamına gelir; bu sayede halihazırda işlettiğiniz her şey, aynı VPS üzerinde barındırılan MCP sunucuları dahil olmak üzere burada çalışır.

Bir sunucuyu tanımlamak, araçlarını doğrudan ajana vermez. Bu işlem, mcp_server_name değeri yukarıdaki name ile eşleşen bir mcp_toolset girdisi aracılığıyla tools listesi üzerinden yapılır. Eğer ajan MCP araçları yokmuş gibi davranıyorsa, başka bir yere bakmadan önce bu iki dizgiyi karakter karakter karşılaştırın.

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

permission_policy, çalışma zamanının ham bir model çağrısının ötesine geçtiği noktadır. always_ask, oturumu duraklatır ve çağrı çalıştırılmadan önce bir insanın onayını bekler. always_allow ise çağrının gerçekleşmesine izin verir. bash değerini always_ask olarak ayarlamak, ajanın siz tam komutu görmeden bir kabuk komutu çalıştıramayacağı anlamına gelir; bu, Claude Code'u bir VPS üzerinde güvenli bir şekilde çalıştırmak istediğinizde başvuracağınız denetim mekanizmasıyla aynıdır.

Üç sandbox modu ve kullanım senaryoları

Kod çalıştıran araç çağrıları bir sandbox içerisinde yürütülür. Arka uç, ortamın config nesnesi içindeki sandbox_provider üzerinden veya konsolda Ayarlar (Settings) ve ardından Sandbox menüsü altından ortam bazında seçilir. Ortamlar, POST /v1/environments adresindeki API üzerinden oluşturulur.

local, kodu çalışma zamanının (runtime) bir alt süreci olarak, ana makinede ve çalışma zamanının kendi kullanıcısı yetkileriyle çalıştırır. Varsayılan moddur; yalnızca siz kullanıcıysanız ve ajan sadece sizin sahip olduğunuz dosyaları okuyorsa makuldür. Bir yalıtım sağlamaz. 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, kendi bellek sınırına ve kendi CPU payına sahip olur; container oturum sonunda kaldırılır. Bir ajan sizin yazmadığınız bir kodu çalıştırdığı anda bu moda geçiş yapın. Bunun 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, her çalıştırma için bir container içeren self-hosted ajan sandbox'ları ile aynı yapıdadır; bu nedenle, kaçan 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ının kubectl bileşenine sahip olması gerekir. Ayrıca ServiceAccount'un, hedef namespace içinde pod oluşturma, silme, alma, listeleme ve izleme (watch) izinlerine, ek olarak exec alt kaynağına yönelik RBAC (rol tabanlı erişim denetimi) yetkisine sahip olması gerekir. Bu mod, yalnızca halihazırda bir küme (cluster) yönetiyorsanız kurulumuna değecek bir seçenektir.

Çalışma zamanı neden 127.0.0.1 adresine bağlı?

Çünkü kimlik doğrulama kapalı olarak başlar. Çalışma zamanı, en az bir API anahtarı mevcut olduğunda bearer-token kimlik doğrulamasını etkinleştirir; yeni bir init kurulumu ise hiçbir anahtar oluşturmaz. 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ı çalışma zamanını herkese açık 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 secret_key alanını yalnızca bir kez döndürür ve bir daha göstermez. İstemciler daha sonra her istekte Authorization: Bearer <key> gönderir.

İkinci olarak, önüne bir reverse proxy yerleştirin ve TLS (transport layer security) sonlandırmasını orada yapın. Çalışma zamanı tasarım gereği düz HTTP sunar ve sertifikaları 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 sonunda tüm çıktı tek seferde dökülür. proxy_read_timeout 3600s önemlidir çünkü varsayılan değer 60 saniyedir; bir dakikadan uzun süre sessiz kalan bir akış, proxy tarafından işlem ortasında kapatılır ve bu hata, çalışma zamanı çökmüş gibi görünür.

Güvenlik duvarında 22 ve 443 numaralı portları açın. 3000 numaralı portu kapalı tutun; çünkü proxy buraya loopback üzerinden erişir ve sunucu dışındaki hiçbir şeyin erişmemesi gerekir.

Anthropic SDK'yı kendi sunucunuza yönlendirme

Çalışma zamanı (runtime), 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. Yerel bir çalışma zamanında bunlar isteğe bağlıdır. Barındırılan bir dağıtım için yazılan kodun burada hiçbir değişiklik yapılmadan çalışabilmesi için mevcutturlar.

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, mevcut olay-sonuç protokolünün üzerinde adlandırılmış kayıt gerektiren istemci tarafı özel araçları da dahil olmak üzere kendi eksikliklerini orada belgelemektedir.

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 getirildiğinden, istemci tek kopyayı elinde tutmak yerine bir günlüğü yeniden oynatmaktadı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ı içindeki .managed-agents/ dizininde yer alı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ı girdileri, bellek deposu girdileri 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 işlem sessizce başarısız olduğunda 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 veriler gruplarıdır. Bellek depoları, kendi erişim ayarları ve yönergeleriyle bir memory_store olarak oturuma bağladığınız adlandırılmış girdileri 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 arasında hatırlama yapar ve gerçekleşen olayları kaydeder.

Tek bir dizin olduğu için, yedekleme işlemini bir bütün olarak gerçekleştirin.

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çılamayacak bir dosya oluşturabilir ve bunu ancak ihtiyaç duyduğunuz gün fark edebilirsiniz. Aracı YAML dosyalarını git üzerinde, durumu ise başka bir yerde tutmak isterseniz, dağıtım dokümantasyonu start üzerinde --data-dir ile durum konumunu sabitlemeyi 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. Eğer ${OPENAI_API_KEY} formunu kullandıysanız sağlayıcı anahtarınız arşiv içinde yer almaz, bu yüzden onu her zaman erişebileceğiniz bir yerde saklayın.

systemd altında çalıştırma

Yerel sandbox modundaki bir araç çağrısının sizin adınıza işlem yapamaması için çalışma zamanına kendi kullanıcısını atayın.

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 kurulumu bunu oluşturmaz, bu nedenle ExecStart, derlenmiş giriş noktasına karşı node ç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 karşılaşacağınız mesajlar

npm run build, npm'den herhangi bir hata almadan sonlandırılıyor. 1 GB RAM kapasiteli bir VPS üzerinde TypeScript derleme işlemi, çekirdeğin bellek yetersizliği (OOM) katili tarafından durdurulur; bu durum npm'e değil, çekirdek günlüklerine raporlanır. journalctl -k | grep -i "out of memory" komutu ile durumu doğrulayın; bu komut, sonlandırılan node sürecini belirten bir satır yazdıracaktır. Swap alanı ekleyin veya derlemeyi daha büyük bir örnek üzerinde gerçekleştirip dist/ dosyasını kopyalayın.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. Başka bir süreç ilgili portu zaten kullanıyor. sudo ss -lntp | grep 3000 komutu bu süreci tanımlar. Söz konusu süreci durdurun veya çalışma zamanını --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ıdaki SSH tünelini kullanın veya reverse proxy kurulumunu tamamlayın. Sorunu --host 0.0.0.0 ile gidermeye çalışmayın, çünkü bir anahtar oluşturulana kadar kimlik doğrulama kapalıdır.

Docker sandbox'ları permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock hatası ile 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; ancak neye izin verdiğinizi anlayın: bu grup ana makinede root yetkilerine sahiptir, dolayısıyla çalışma zamanına kendi kullanıcısını atamanızın sağladığı güvenlik avantajının bir kısmını ortadan kaldırır.

Kubernetes sandbox'ları Error from server (Forbidden) hatası ile 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 her istek 401 hatası döndürüyor. Kimlik doğrulama, ilk anahtar oluşturulduğunda devreye girer ve hem konsol hem de API için geçerli olur. Authorization: Bearer <key> gönderin; eğer anahtarı kaybettiyseniz yeni bir tane oluşturun, çünkü secret_key yalnızca bir kez gösterilir ve okunabilir bir biçimde saklanmaz.

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 URL'ye ulaşıp ulaşamadığını kontrol edin. 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

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

Evet, OpenAI uyumlu bir uç noktanız varsa çalıştırabilirsiniz. Çalışma zamanı (runtime) OpenAI, Anthropic ve OpenAI uyumlu sağlayıcıları destekler; dolayısıyla OpenAI API 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 sunucuya yönlendirin. Çalışma zamanı kendi içinde bir model barındırmaz, bu nedenle çağrılara yanıt verecek bir kaynağın bulunması gerekir.

Çalışma zamanını genel bir port üzerinden dış dünyaya açmak güvenli midir?

Varsayılan kurulumda güvenli değildir. Çalışma zamanı 127.0.0.1:3000 adresine bağlanır ve kimlik doğrulaması kapalı olarak başlar; çözüm, farklı bir bağlama adresi kullanmak değildir. Bir API anahtarı oluşturun veya MANAGED_AGENTS_API_KEY ayarını yapılandırarak bearer-token kimlik doğrulamasını etkinleştirin. 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 yapıları arasındaki fark nedir?

local, araç kodunu çalışma zamanının bir alt süreci olarak ana makinede, çalışma zamanı kullanıcısının izinleriyle ve herhangi bir yalıtım olmadan çalıştırır. docker, her oturuma kendi dosya sistemi, bellek sınırı ve CPU payı olan ayrı bir container atar ve oturum bittiğinde bu container'ı kaldırır. kubernetes, oturumu bir pod olarak çalıştırır ve kubectl exec ile yönetir; bu yapı, çalışma zamanı imajı içinde kubectl bileşenini, pod'lar üzerinde RBAC yetkilendirmesini ve hedef namespace içinde exec alt kaynağını gerektirir.

Tam olarak neleri yedeklemem gerekiyor?

Çalışma alanındaki .managed-agents/ dizinini yedeklemelisiniz. Bu dizin; config.yaml içeriğini, ajanları, oturumları, kimlik bilgisi kasası kayıtlarını ve bellek girdilerini tutan data.db SQLite veritabanını, ayrıca yüklenen dosyaları, yetenek paketlerini ve oturum anlık görüntülerini içerir. SQLite veritabanının arşivleme sırasında yazılmasını önlemek 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 nedenle bunları ayrı bir yerde saklayın.

Neden main dalı yerine v0.3.2 etiketini klonlamalıyım?

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 sürekli değişebilir ve bir rehber yazıldıktan sonra siz komutu çalıştırana kadar bir yapılandırma anahtarının ismi değiştirilmiş olabilir. Proje ayrıca, npm üzerindeki kapsamlandırılmamış managed-agents paketinin bu projeye ait olmadığını, dolayısıyla npx managed-agents komutunun alakasız bir şey kuracağını belirtmektedir. v0.3.1 sürümü, temel olarak bu npm hızlı başlangıç yöntemini, sabitlenmiş etiketli kaynak yoluyla değiştirmek için yayınlanmıştır.