Sandboxes

Sandboxes nedir?

Bir yapay zekâ ajanı kod üretiyor ve o kodun çalıştırılması gerekiyor. Ya da kullanıcıların gönderdiği kodu çalıştıran bir platform kuruyorsun. Her iki durumda da temel soru aynı: güvenilmeyen kodu nereye koyacaksın?

Bir Worker bunu yapamaz — pip install çalıştıramaz, python3 süreci başlatamaz, kabuğu yoktur. Ham bir Container yapabilir ama Dockerfile’ı, içindeki HTTP sunucusunu ve yaşam döngüsünü sen yazmak zorundasın.

Sandbox SDK ikisinin arasını doldurur: Cloudflare hazır bir Ubuntu image’ı ve içinde çalışan bir sunucu verir, sen Worker’ından TypeScript API’siyle sürersin.

Cloudflare’in kendi tanımı:

“The Sandbox SDK enables you to run untrusted code securely in isolated environments. Built on Containers, Sandbox SDK provides a simple API for executing commands, managing files, running background processes, and exposing services — all from your Workers applications.”

Üç katmanlı mimari

Bu yüzden Sandboxes’ın ayrı bir fiyatı yoktur — üç katmanın toplamı faturalanır.

Nasıl çalışır?

İzolasyon modeli

Her sandbox kendi sanal makinesinde çalışır. Cloudflare sorumluluğu açıkça ikiye ayırıyor:

SDK’nın koruduğu şeyler:

“Sandbox-to-sandbox access (VM isolation) / Resource exhaustion (enforced quotas) / Container escapes (VM-based isolation)”

Senin uygulaman gereken şeyler:

“Authentication and authorization / Input validation and sanitization / Rate limiting / Application-level security (SQL injection, XSS, etc.)”

Yaşam döngüsü

keepAlive: true verilirse container 30 saniyede bir heartbeat gönderir ve hiç zaman aşımına uğramaz. Ama resmî uyarı: “Containers with keepAlive: true require explicit management since they do not timeout automatically.” — yani faturayı sen durdurmak zorundasın.

Session’lar güvenlik sınırı değildir

Bir sandbox içindeki session’lar, aynı bilgisayardaki terminal sekmeleri gibidir. Session’a özel olan: kabuk ortamı, çalışma dizini, ortam değişkenleri. Paylaşılan: dosya sistemi ve süreçler.

@next sürümünde session kavramı tamamen kaldırıldı.

Subrequest tuzağı

Bu, Sandboxes’ta en sık karşılaşılan çalışma zamanı hatasıdır.

Ne zaman kullanılır, ne zaman kullanılmaz

Uygun olduğu işler

• LLM’in ürettiği kodu çalıştırma
• Kod yorumlayıcı / notebook semantiği
• Kullanıcı gönderimi kod çalıştıran platformlar
• CI benzeri işler: klonla, kur, test et
• Yapay zekâ kodlama ajanlarına çalışma ortamı verme

Uygun olmadığı işler

• Düz bir Worker yeterliyse. Sandbox, container maliyeti ve 1–3 saniyelik cold start ekler.
• Kalıcı state gerekiyorsa. Container durduğunda her şey silinir.
• Tek sandbox içinde çok kiracılı sınır kurmak. Session’lar bunu sağlamaz.
• Kendi üretim runtime’ını tam kontrol etmek istiyorsan. Ham Containers kullan — Dockerfile senin olur, SDK/image sürüm bağımlılığını miras almazsın.
• Ücretsiz plan. Kullanılamaz.
• Masaüstü / bilgisayar kullanımı otomasyonu. desktop özelliği 0.10.2’de kaldırıldı.

Somut örnekler

Ortak yapılandırma:

{
  "name": "sandbox-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-31",
  "compatibility_flags": ["nodejs_compat"],
  "vars": { "SANDBOX_TRANSPORT": "rpc" },
  "containers": [{ "class_name": "Sandbox", "image": "./Dockerfile" }],
  "durable_objects": { "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }] },
  "migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }]
}

# Etiketi kurduğun npm sürümüyle eşleştir — doküman örneklerindeki sürümü kopyalama
FROM docker.io/cloudflare/sandbox:0.12.9-python
RUN pip install --no-cache-dir scikit-learn

1. LLM’in ürettiği kodu çalıştırma

import { getSandbox, proxyToSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";

export default {
  async fetch(request, env) {
    // proxyToSandbox HER ZAMAN ilk satır olmalı, yoksa preview URL'ler bozulur
    const proxy = await proxyToSandbox(request, env);
    if (proxy) return proxy;

    const kullaniciId = await kimlikDogrula(request);
    if (!kullaniciId) return new Response("Yetkisiz", { status: 401 });

    const { kod } = await request.json();

    // Kullanıcı başına AYRI sandbox — tek gerçek izolasyon sınırı bu
    const sandbox = getSandbox(env.Sandbox, `kullanici-${kullaniciId}`, {
      enableDefaultSession: false,
      normalizeId: true,        // büyük harfli kimlikleri küçültür
    });

    const ctx = await sandbox.createCodeContext({ language: "python" });
    const sonuc = await sandbox.runCode(kod, { context: ctx, timeout: 30_000 });

    return Response.json({
      stdout: sonuc.logs.stdout,
      stderr: sonuc.logs.stderr,
      deger: sonuc.results?.[0]?.text,
      hata: sonuc.error ?? null,
    });
  },
};

2. Kod yorumlayıcı — notebook semantiği

const ctx = await sandbox.createCodeContext({ language: "python" });

await sandbox.runCode("import math; yaricap = 5", { context: ctx });
const sonuc = await sandbox.runCode("math.pi * yaricap ** 2", { context: ctx });

console.log(sonuc.results[0].text);   // "78.53981633974483"

Resmî ifade: “Contexts maintain state (variables, imports, functions) across executions.” Üretimde bağlamı açıkça oluşturmak öneriliyor — böylece state öngörülebilir kalır.

3. CI benzeri iş

import { getSandbox, parseSSEStream } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";

// Çalışma başına tek kullanımlık sandbox
const sandbox = getSandbox(env.Sandbox, `test-${Date.now()}`);
try {
  await sandbox.gitCheckout(depoUrl, { branch, depth: 1, targetDir: "depo" });

  const akis = await sandbox.execStream("cd /workspace/depo && npm test");
  let cikisKodu = 0;
  for await (const olay of parseSSEStream(akis)) {
    if (olay.type === "stdout" || olay.type === "stderr") console.log(olay.data);
    else if (olay.type === "complete") cikisKodu = olay.exitCode;
  }
  return Response.json({ basarili: cikisKodu === 0, cikisKodu });
} finally {
  await sandbox.destroy();   // tek kullanımlık sandbox'ı MUTLAKA temizle
}

4. Uzun süren geliştirme sunucusu ve genel URL

const sandbox = getSandbox(env.Sandbox, `onizleme-${projeId}`, { keepAlive: true });

await sandbox.writeFile("/workspace/app.py", uretilenUygulama);
await sandbox.startProcess("python -m http.server 8080 --directory /workspace");

const tunel = await sandbox.tunnels.get(8080);
return Response.json({ url: tunel.url });   // https://<rastgele>.trycloudflare.com

Resmî güvenlik notu: “the hostname itself is the access control: anyone who knows the URL can reach the service.” Erişimi kesmek için await sandbox.tunnels.destroy(8080).

5. Sandbox’a sır vermeden dış API çağırma

export class Sandbox extends BaseSandbox {
  // Sandbox içindeki kod token'ı asla göremez
}

Sandbox.outbound = async (request, env) => {
  const url = new URL(request.url);
  if (url.hostname === "api.ornek.com") {
    const headers = new Headers(request.headers);
    headers.set("Authorization", `Bearer ${env.API_TOKEN}`);
    return fetch(new Request(request, { headers }));
  }
  return new Response("Engellendi", { status: 403 });
};

Demo 1: LLM kodunu güvenle çalıştırma

Adım 1 — Kurulum

docker info
npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
cd my-sandbox
npm run dev      # ilk çalıştırma image'ı derler, 2-3 dakika sürer

Terminal — npm run dev çıktısı, Docker image derleme adımları ve bindings listesi

Adım 2 — Python kodu çalıştır

curl -X POST http://localhost:8787/calistir \
  -H 'content-type: application/json' \
  -d '{"kod": "import pandas as pd; print(pd.DataFrame({\"a\":[1,2,3]}).sum())"}'

curl yanıtı — stdout içinde pandas çıktısı; sandbox'ın gerçekten Python çalıştırdığı görünsün

Adım 3 — Bağlam kalıcılığını doğrula

İki ardışık istek — ilkinde değişken tanımlanıyor, ikincisinde kullanılıyor ve değeri korunmuş görünüyor

Adım 4 — Yayına al

npx wrangler deploy
npx wrangler containers list

wrangler deploy çıktısı ve ardından containers list ile sandbox container'ının görünmesi

Demo 2: İzolasyon ve subrequest tuzağı

Adım 1 — Paylaşılan sandbox’ın tehlikesini göster

İki farklı kullanıcı olarak aynı sandbox kimliğine yaz ve oku.

İki farklı kullanıcı olarak yapılan istekler — ikincisinin birincinin yazdığı dosyayı okuyabildiğini gösteren çıktı

Adım 2 — Kullanıcı başına sandbox’a geç

Aynı test tekrarlandığında ikinci kullanıcının dosyayı bulamadığını gösteren çıktı

Adım 3 — Subrequest sınırına çarp

SANDBOX_TRANSPORT ayarını kaldırıp ardışık 60 SDK çağrısı yap.

wrangler tail veya tarayıcı çıktısında 'Too many subrequests' hatası ve kaçıncı çağrıda oluştuğu

Adım 4 — RPC taşımasına geç

SANDBOX_TRANSPORT=rpc eklendikten sonra aynı 60 çağrının hatasız tamamlandığı çıktı

Adım 5 — Uyku sonrası state kaybını doğrula

Dosya yazıldıktan sonra beklenip tekrar okunduğunda dosyanın bulunamadığını gösteren iki çıktı

Ölçüm

Fiyatlandırma

Resmî ifade: “Sandbox SDK pricing is determined by the underlying Containers platform it’s built on.” Ayrı bir Sandbox fiyat listesi yoktur.

Fatura üç kalemden oluşur:

Instance tipleri, hesap limitleri (6 TiB bellek, 1.500 vCPU, 50 GB image deposu) ve cold start süreleri de Containers ile birebir aynıdır.

Sandbox’a özel sınırlar

Lisanslama ve hukuki çerçeve

Sandbox hizmeti tescillidir; Cloudflare Hizmet Şartları kapsamındadır. SDK npm üzerinden @cloudflare/sandbox olarak dağıtılır.

Güvenilmeyen kod çalıştırmanın hukuki boyutu: Sandbox içinde kullanıcıların veya bir LLM’in ürettiği kodu çalıştırıyorsan, o kodun ne yaptığından sen sorumlusun. Cloudflare’in Kabul Edilebilir Kullanım Politikası sandbox içinden yapılan işlemleri de kapsar. Egress’i kilitlemek yalnızca güvenlik değil, sorumluluk yönetimi açısından da anlamlıdır.

Veri konumu: Containers ile aynı — bölge kısıtları constraints.regions ile verilir, Türkiye tanımlı bir bölge değildir.

Sık yapılan hatalar

Tüm kullanıcılar için tek sandbox. Cloudflare’in kendi etiketlediği anti-desen. Kullanıcılar birbirinin dosyalarını okur.

Session’ları izolasyon sanmak. Session’lar dosya sistemini ve süreç uzayını paylaşır.

npm sürümü ile Docker image etiketinin uyuşmaması. En sık karşılaşılan tuzak; doküman örnekleri bayat sürüm pinliyor.

Büyük harfli sandbox kimliği. Preview URL’ler hostname’i küçültür, yani "Proje-123" var olmayan bir Durable Object’e yönlenir. Küçük harf kullan veya normalizeId: true ver.

proxyToSandbox()’ı ilk satıra koymamak. Preview URL’ler sessizce bozulur.

Kullanıcı girdisini kabuğa enterpolasyon yapmak. Doküman örneği: await sandbox.exec(`cat ${dosyaAdi}`) → kullanıcı dosya.txt; rm -rf / yazabilir. Doğrusu writeFile + sabit komut.

Sandbox’a dış API anahtarı vermek. İçerideki her kod onu okuyabilir. Outbound handler kullan.

Tek kullanımlık sandbox’larda destroy() çağırmamak. Uyuyana kadar provision edilmiş bellek ve disk için ödemeye devam edersin.

keepAlive: true verip unutmak. Otomatik zaman aşımı olmadığı için fatura durmaz.

Kullanımdan kalkan API’lerle yeni kod yazmak. Resmî ifade: “Do not build new work on them.”