Docker Sandbox’ta kodu nerede tutmalı: mount, clone mode, mountless

Docker, Docker Sandbox’ta agent’ların çalışacağı kod için üç yer öneren bir yazı yayımladı: host checkout’unu mount etmek, Git worktree veya clone mode ile agent’a kendi checkout’unu vermek ya da repo’yu tamamen sandbox içinde tutmak. Yazı, sbx aracının bu seçenekleri nasıl desteklediğini ve her birinin Git erişimini, bağımlılıkları ve önizlemeyi nasıl etkilediğini ele alıyor.

Docker Sandbox nedir?

Docker Sandbox, yapay zekâ coding agent’larını host sistemden yalıtılmış bir ortamda çalıştırmak için Docker’ın geliştirdiği bir özelliktir. Agent’ın komut çalıştırması, paket kurması ve dosya düzenlemesi sandbox içinde kalır. Komut satırında sbx aracıyla yönetilir. Agent’ı doğrudan geliştirici makinesinde veya uzak bir geliştirme ortamında çalıştırmak bilinen alternatiflerdir.

Git worktree nedir, ne için kullanılır?

Git worktree, tek bir Git repo’suna bağlı birden fazla çalışma dizini açmayı sağlayan Git özelliğidir. Her worktree ayrı bir branch’i checkout eder, böylece aynı repo’da birden çok görevi birbirini bozmadan yürütebilirsiniz. Linked worktree’lerde .git bir dizin değil, ana repo’daki metadata’yı gösteren bir dosyadır. Alternatifi repo’yu ayrı dizinlere tekrar klonlamaktır.

Docker Sandbox içinde üç yerleşim

Agent’ı sandbox’a koymak işin yarısı. Kodun nerede durduğu, agent’ın çıktısına ne kadar yakın duracağınızı belirliyor. Docker’ın tarif ettiği seçenekler şunlar:

• Doğrudan mount: sbx run proje dizinini sandbox içinde aynı absolute path’e bağlıyor. Editörünüz ve host’taki dev server’ınız değişikliği anında görüyor.
• Host worktree: her görev ayrı dizin ve branch alıyor, her worktree kendi sandbox’ında çalışıyor.
• Clone mode: host kaynağı read-only mount ediliyor, agent bağımsız bir clone üzerinde çalışıyor.
• Mountless: repo yalnızca sandbox içinde duruyor, uzak bir geliştirme makinesi gibi.

Seçimi belirleyen soru basit. Diff’i satır satır izliyorsanız mount işinizi görür. Sabah üç görev verip akşam pull request bakıyorsanız clone mode veya mountless daha az sürtünme çıkarır.

İki sessiz tuzak: esbuild ve .git dosyası

İlk tuzak bağımlılıklar. Mount edilmiş checkout’a agent’ın kurduğu paketler host’a da yazılıyor. Docker, esbuild gibi native binary içeren paketlerin Linux sandbox’ta çalışıp macOS veya Windows host’ta kırılabileceğini not ediyor. Host’ta yeniden kurarsanız sorun bu kez ters yöne dönüyor. Uygulamayı tek bir ortamda çalıştırmaya karar verin veya iki ortam için ayrı kurulum tutun.

İkinci tuzak linked worktree. Worktree’nin .git dosyası, mount dışında kalan metadata’yı gösteriyor. Agent dosyaları düzenleyebiliyor, fakat git status, branch açma ve commit host’ta yapılmak zorunda. Host worktree akışı standart Git komutlarıyla kuruluyor:

git worktree add -b feature ../my-project-feature
cd ../my-project-feature
sbx run claude

Agent’ın kendi commit’lerini atmasını istiyorsanız clone mode’a geçin.

Clone mode ile işi geri almak

Clone mode’da agent’ın branch değişiklikleri ve paket kurulumları kendi checkout’unda kalıyor. Sonucu almak bir teslim adımına dönüşüyor. Sandbox çalışırken sbx’in host’a eklediği Git remote’undan commit edilmiş branch’leri fetch edebilirsiniz. Remote’un adını görmek için:

git remote -v

Bu yol yalnızca sandbox çalışırken ve yalnızca commit edilmiş işte geçerli. Agent’a görev sonunda commit atmasını açıkça söyleyin, sandbox’ı durdurmadan önce fetch edin.

Diğer yol agent’ın repo’nun asıl remote’una push etmesi. Bunun için sandbox içinde yazma yetkisi olan bir kimlik bilgisi gerekir. O token’ı tek repo ile sınırlayın, ana branch’e branch protection koyun; agent’ın push ettiği her şey pull request’ten geçsin.

Mountless sandbox ve port yayınlama

Mountless düzende proje ve araçları agent oturumları ile sandbox restart’ları boyunca kalıcı. Agent her özellik için içeride worktree açıp branch push edebiliyor. Yeni görev için host’ta worktree ve sandbox hazırlamanız gerekmiyor. Shell için sbx exec, editör için SSH kullanılıyor.

Bedel önizlemede. Dev server sandbox içinde 0.0.0.0’a bind olmalı ve port host’tan yayınlanmalı:

sbx ports my-sandbox --publish 8080:8080

Aynı sandbox’taki görevler araç ve servisleri paylaşıyor. İki görev aynı portta dev server açmaya kalkarsa çakışır; ortamı değiştiren işlemleri sıraya koyun. Bağımsız ortam gerekiyorsa ayrı sandbox açın, çünkü branch’ler tek bir çalışma dizinindeki eşzamanlı düzenlemeyi ayırmıyor.

Bu düzende veri kaybedebilirsiniz. Sandbox silindiğinde yalnızca orada duran dosyalar da gidiyor. Push edilmemiş bir branch’teki iş silinebilir. Ortamı bir environment file ile tekrar üretilebilir yapın; Docker, repo’yu oluşturma anında klonlamak için topluluğun github-clone kit’ini örnek gösteriyor.

Birden çok repo ve nereden başlamalı

API değişikliği frontend değişikliği istiyorsa birden fazla dizini tek sandbox’a mount edebilirsiniz. Referans repo’ları read-only bağlayın. Yazılabilir her checkout’un branch’ini ayrıca takip etmeniz ve dizinini görev sonunda temizlemeniz gerekir. Jganoff/wsp gibi bir workspace yöneticisi seçili repo’ları normal clone olarak topluyor; her birinin kendi Git metadata’sı olduğu için agent Git erişimini kaybetmiyor.

Başlangıç sırası olarak:

• Tek görev, yakın takip: Docker Sandbox içinde doğrudan mount ile başlayın, bağımlılıkları tek ortamda kurun.
• Paralel görevler: clone mode’a geçin, teslimi fetch veya pull request ile yapın.
• Uzun ömürlü proje: proje başına bir mountless Docker Sandbox açın, environment file’ı repo’da tutun.

Docker’ın Git workflows dokümantasyonu direct mount, clone mode ve host worktree mekaniğini anlatıyor; clone mode’u açan komut ve seçenekler orada.