Yazan SandBase Agent Runtime Kendi Sunucunuzda Nasıl Kurulur?
SandBase Harness v0.3.2 kurulumu, agent YAML yapılandırması ve MCP sunucuları ile kendi VPS ortamınızı hazırlayın. Anthropic SDK uç noktasını yerel sunucunuza yönlendirin.
SandBase agent çalışma zamanını kendi sunucunuzda barındırdığınızda elde ettikleriniz
SandBase agent çalışma zamanını 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 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 çalışma zamanını her iki yönde de ilgi çekici kılan özellik budur: Anthropic SDK ile kod yazıp baseURL adresini kendi sunucunuza yönlendirebilir, daha sonra aynı kodu 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 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.
gitve 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 -vnode -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.2 etiketinden kurun
Kurulumu her zaman bir etiketten yapın, asla güncellenen bir daldan (branch) yapmayın. main ile 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. v0.3.2, 16 Ağustos 2026 itibarıyla güncel etikettir.
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 buildnpm 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 aynı olur. npm install ise daha yeni sürümleri çözümleyebilir; sabitlenmiş bir etiketin sessizce sabitlenmiş olmaktan çıkması bu şekilde gerçekleşir.
Şimdi bir çalışma alanı (workspace) oluşturun. Çalışma alanı, aracı dosyalarınızı ve tüm çalışma zamanı durumunu tutan ayrı bir dizindir. Bunu 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 startinit, çalışma alanına bir .managed-agents/ dizini yazar. start, konsolu http://127.0.0.1:3000/dashboard adresinde ve API'yi http://127.0.0.1:3000/v1 adresinde ayağa kaldırır. Bunların hiçbiri henüz dizüstü bilgisayarınızdan erişilebilir durumda değildir; 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-serverO uzun node .../dist/index.js yolu yorucu olmaya başladığında, 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.envBu 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-commanderDosyayı 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.
Üç 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 nesnesindeki sandbox_provider üzerinden veya konsolda Ayarlar ardından Sandbox bölümünden ortam bazında seçilir. 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. 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çin. Bunun maliyeti, çalışma zamanı kullanıcısının Docker socket erişimine ihtiyaç duymasıdır; 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, 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 yönelik RBAC (rol tabanlı erişim denetimi) iznine sahip olması gerekir. Bu mod, yalnızca halihazırda bir küme (cluster) çalıştırıyorsanız kurulum zahmetine değer.
Ç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 maruz bırakı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ğrulamasını 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 daha sonra her istekte Authorization: Bearer <key> gönderir. Bir anahtar, paylaşılan bir kimlik anlamına gelir; bu nedenle eğer istediğiniz, sağlayıcı anahtarlarının tek bir ağ geçidinde tutulduğu, ekip arkadaşı başına ayrı ve yalıtılmış bir aracı ise, 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. Çalışma zamanı 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, işlem bittiğinde ise 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ış, aradaki proxy tarafından kapatılır ve bu hata, çalışma zamanının çökmesi 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 kutunun dışındaki hiçbir şeyin erişmemesi gerekir.
Anthropic SDK'yı kendi sunucunuza yönlendirme
Çalışma zamanı (runtime), CMA biçimli bir /v1 arayüzü 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 anthropic-beta: managed-agents-2026-04-01 ve anthropic-beta: agent-memory-2026-07-22 beta başlıklarını da kabul eder. Yerel bir çalışma zamanında bunlar isteğe bağlıdır. 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ışabilmesi için mevcuttur.
Uyumluluk tam değil, yakındır. Bir arayüzün 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. İstemci tarafındaki özel 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 baştan oynatmak yerine gördüğünüz son olaydan itibaren 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ği için, istemci tek kopyayı 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ı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/sandbaseBunu /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.targetProjenin 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/dashboardSağ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'e sahip 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. Durumu, sonlandırılan node sürecini adıyla belirten bir satır yazdıran journalctl -k | grep -i "out of memory" ile 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ç ilgili portu halihazırda kullanıyor. sudo ss -lntp | grep 3000 bu süreci isimlendirir. Söz konusu süreci durdurun ya da ç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. Bunu --host 0.0.0.0 ile onarmaya ç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ıyla başarısız oluyor. sandbase kullanıcısı docker grubuna dahil değil. Sorunu sudo usermod -aG docker sandbase ile çözün ve servisi yeniden başlatın. Verdiğiniz yetkinin kapsamını anlayın: bu grup ana makinede root yetkisine 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ı döndürecektir.
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; 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. tools bloğundaki mcp_server_name değerini mcp_servers içindeki name ile karşılaştırın, ardından çalışma zamanının sunucunun kendisinden curl -i <url> ile 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'i OpenAI veya Anthropic anahtarı olmadan ç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; bu nedenle 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 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ı yaparak 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'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 izolasyon olmadan çalıştırır. docker, her oturuma kendi dosya sistemi, bellek sınırı ve CPU payı ile ayrı bir container atar ve oturum bittiğinde bu container'ı kaldırır. kubernetes, oturumu bir pod olarak çalıştırır ve bunu kubectl exec ile yönetir; bu yöntem, çalışma zamanı imajı içinde kubectl bulunmasını, pod'lar üzerinde RBAC yetkilendirmesini ve hedef ad alanında exec alt kaynağının tanımlanmasını gerektirir.
Tam olarak neleri yedeklemem gerekiyor?
Çalışma alanındaki .managed-agents/ dizinini yedeklemelisiniz. Bu dizin; config.yaml, ajanları, oturumları, kimlik bilgisi kasası kayıtlarını ve bellek girişlerini içeren data.db SQLite veritabanını, ayrıca yüklenen dosyaları, yetenek paketlerini ve oturum anlık görüntülerini barındırır. SQLite'ın arşivleme sırasında yazma işlemi yapmaması 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.2 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 birebir eşleşir. main sürekli değişir ve bir rehber yazıldıktan sonra siz onu çalıştırana kadar bir yapılandırma anahtarının ismi değiştirilmiş olabilir. Proje ayrıca, npm üzerindeki kapsam belirtilmemiş managed-agents paketinin bu projeye ait olmadığını, dolayısıyla npx managed-agents komutunun ilgisiz bir şey kuracağını belirtmektedir. v0.3.1 sürümü, temel olarak bu npm hızlı başlangıç yöntemini sabitlenmiş etiketli kaynak yolu ile değiştirmek için yayınlanmıştır.