dsh Yapılandırması: API Anahtarı ve Model Ayarları

dsh yapılandırmasının konumu

dsh (DeepSeek Harness), yapılandırmasını tek bir dizinde tutar: $DSH_HOME; bu dizin varsayılan olarak ~/.dsh yolundadır. Web arayüzünde yaptığınız tüm ayarlar burada düz metin dosyaları olarak kaydedilir. Bu dizini başka bir sunucuya kopyaladığınızda, yeni sunucu eskisiyle aynı şekilde davranır.

İşlem yapacağınız her şeyi dört yol barındırır.

• ~/.dsh/settings.yaml, sağlayıcı ve model rotalarınız dahil olmak üzere elle veya arayüz üzerinden yazılan ayarları tutar.
• ~/.dsh/.credentials.yaml, gizli bilgileri tutar. Ayarlar yalnızca kimlik bilgisine bir referans içerir, bu nedenle anahtarın kendisi tek bir dosyada bulunur.
• ~/.dsh/profiles/ adlandırılmış profilleri, ~/.dsh/storages/ ise kaydedilmiş oturumları tutar.
• ~/.dsh/cordis.patch.yml, kendi yama katmanınızdır. Her profil için yerleşik yapılandırmanın üzerine uygulanır.

DeepSeek, bu aracı 17 Ağustos 2026 tarihinde MIT lisanslı bir geliştirici önizlemesi olarak duyurmuştur ve README dosyası, uyumluluğu bozacak değişikliklerin olacağını belirtmektedir. Bu kılavuzdaki alan adları ve yollar, Ağustos 2026 itibarıyla depo belgeleriyle uyumludur. Bir yapılandırmayı herhangi bir kılavuzdan (bu kılavuz dahil) kopyalamadan önce, kurduğunuz sürümün belgeleriyle karşılaştırın; çünkü önizleme sürümlerinde sürümler arası isim değişiklikleri yapılabilmektedir.

İlk çıktı için gereken asgari işlemler

dsh, 22 serisinde Node.js 22.19 veya üzerini ya da 24 ve üzeri sürümleri gerektirir. Node 23 bu aralığın dışındadır. Sürüm uyuşmazlığı başlatma sırasında başarısızlığa yol açtığı ve hata mesajı bozuk bir paket gibi göründüğü için önce sürümü kontrol edin.

node -v
npx @deepseek-ai/dsh web

npx, paketi npm kayıt defterinden indirir ve Web arayüzünü http://127.0.0.1:3080 üzerinde başlatır. Loopback adresine bağlandığı için, güvenlik duvarınız izin verse bile port başka bir makineden erişilebilir olmaz. Bir VPS üzerinde, 3080 numaralı portu internete açmak yerine SSH üzerinden yönlendirin.

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

Dizüstü bilgisayarınızda http://127.0.0.1:3080 adresini açın, ardından Settings ve Models bölümlerine gidin. DeepSeek kartında bir API anahtarı alanı bulunur. platform.deepseek.com adresinden aldığınız anahtarı buraya yapıştırın ve kaydedin. Çalışan sunucu kimlik bilgilerini bellekte tuttuğu ve referansı anlık olarak çözümlediği için model rotası yeniden başlatmaya gerek kalmadan hemen kullanılabilir hale gelir. Uzak bir sunucudaki dsh Web arayüzüne erişim tünel ve reverse proxy durumlarını, DeepSeek Harness kurulumu ise bu kılavuzun varsaydığı sunucu hazırlığını kapsar.

Kaydettikten sonra uygulamanın oluşturduğu dosyayı inceleyin.

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

settings.yaml, .credentials.yaml ve profiles/ dosyalarını görmelisiniz. Eğer stat, 600 dışında bir mod çıktısı verirse chmod 600 ~/.dsh/.credentials.yaml komutunu çalıştırın. Grup tarafından okunabilir veya herkes tarafından okunabilir bir kimlik bilgisi dosyası, anahtarınızı sunucudaki diğer tüm hesaplara açık hale getirir.

Tarayıcı olmadan ilk çalıştırma için tek bir komut yeterlidir.

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

Headless profili tek bir oturum çalıştırır ve nihai yanıtı yazdırır.

Ortam değişkenleri veya yapılandırma dosyası

dsh aracına anahtar sağlamanın iki yolu vardır ve bunlar birbirinin yerine kullanılamaz.

Bir katalog sağlayıcısı (DeepSeek, Anthropic, OpenAI ve yerleşik listedeki diğerleri), anahtarını Modeller sayfası üzerinden alır. Değer ~/.dsh/.credentials.yaml içine girilir ve ayarlarınız yalnızca buna bir referans tutar. Web arayüzü, anahtarı kaydettikten sonra bir daha asla göstermez.

Özel bir sağlayıcı, bunun yerine apiKeyEnv ile bir ortam değişkeni belirtebilir. Bu, belgelerin ~/.dsh/settings.yaml için sunduğu biçimdir.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

Önce Web arayüzü üzerinden bir sağlayıcı ekleyin, ardından ~/.dsh/settings.yaml dosyasını açın ve yazdığı yapıyı kopyalayın. Geliştirici önizlemesi sırasında iç içe geçme yapısı en çok değişmesi muhtemel kısımdır ve uygulamanın az önce yazdığı dosya her zaman günceldir.

apiKeyEnv, giriş kabuğunuzdan değil, dsh sürecinin ortamından okunur. Etkileşimli bir oturumda dışa aktarılan bir anahtar, bir systemd birimi için görünmezdir; bu nedenle elle dsh web yazdığınızda çalışan aynı yapılandırma, bir servis altında MISSING_CREDENTIAL hatası döndürür. Birime kendi dosyasını verin.

[Service]
EnvironmentFile=/etc/dsh/dsh.env

Bu dosyayı, servisi çalıştıran kullanıcının sahipliğinde ve 600 modunda tutun.

Model seçimi ve yeniden adlandırılamayan kimlik

Yapılandırılmış her sağlayıcı, model seçicide görünür. Bir model seçmek, onu yeni oturumlar için varsayılan hale getirir. Mevcut oturumlar, içlerinde kayıtlı olan modeli korur; bu nedenle model değiştirmek eski bir konuşmayı yeniden yazmaz.

Sağlayıcı Kimliği (Provider ID) kalıcıdır. İstekler, kaydedilmiş oturumlar, model varsayılanları ve kimlik bilgisi referanslarının tümü bu kimliğe işaret eder, bu yüzden bir yeniden adlandırma düğmesi bulunmaz. Kimliği değiştirmek, yeni bir sağlayıcı oluşturup eskisini silmek anlamına gelir. test2 yerine local-ollama gibi, uzun vadede kullanabileceğiniz bir isim seçin.

Aksi belirtilmedikçe modeller yalnızca metin tabanlıdır. Görüntü desteğini tanımlamak için bir model girişine input: [text, image] ekleyin veya katalogda tanımlanmayan modeller için yedek olarak rota düzeyinde defaultInput ayarını yapın. DeepSeek'in kendi chat-completions rotası yalnızca metin tabanlıdır ve başka türlü yapılandırılamaz; bu nedenle, bu rotaya eklenen bir görüntü, herhangi bir veri gönderilmeden önce reddedilir.

dsh aracını yerel bir uç noktaya yönlendirerek kodunuzu sunucuda tutun

Ollama, http://127.0.0.1:11434/v1 üzerinde OpenAI uyumlu bir API sunar. dsh, özel bir sağlayıcı aracılığıyla herhangi bir OpenAI uyumlu temel URL ile iletişim kurabildiğinden, ikisi arasında başka bir katman olmadan bağlantı kurulur. Öncelikle model sunucusunu kurun: Ollama ile VPS üzerinde LLM barındırma rehberi, kurulum ve model çekme işlemlerini kapsar.

dsh ile işlem yapmadan önce uç noktanın yanıt verdiğini doğrulayın.

ollama list
curl -s http://127.0.0.1:11434/v1/models

ollama list, çektiğiniz her modelin tam etiketini yazdırır. Bu dizgiyi kopyalayın. curl, aynı modelleri JSON formatında döndürür. Boş bir liste, Ollama'nın çalıştığını ancak hiçbir modelin çekilmediğini gösterir. Connection refused ise Ollama'nın çalışmadığını veya 11434 numaralı portu dinlemediğini belirtir.

Şimdi sağlayıcıyı ekleyin. Ollama bir API anahtarı alanı gerektirir ancak değerini dikkate almaz, bu nedenle boş olmayan herhangi bir dizgi iş görür.

llm-pi-ai:
  providers:
    local-ollama:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      models:
        - id: <the exact tag printed by ollama list>

Değişkeni, dsh sürecinin görebileceği şekilde dışa aktarın.

sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.env

Bu kurulum denemelerinde karşılaşılan hataların neredeyse tamamı üç başlıkta toplanır. MISSING_CREDENTIAL, dsh aracının apiKeyEnv tarafından adlandırılan değişkeni okuyamadığı anlamına gelir; bu durumda terminalinizin ortamını değil, sürecin ortamını kontrol edin. UNKNOWN_MODEL, id değerinin yapılandırılmış bir modelle eşleşmediğini gösterir; bu nedenle değeri, iki noktadan sonraki etiket dahil olmak üzere ollama list ile karakter karakter karşılaştırın. Kullanılabilir modelleri getirirken alınan 401 hatası, temel URL'nizde GET /models yolunu çağıran model keşfi sürecinden kaynaklanır; bu yolu sunmayan uç noktalar için modellerin elle girilmesi gerekir.

Bir diğer tuzak ise temel URL'dir. /v1 kısmını eklemezseniz istekler Ollama'nın sunmadığı yollara gider, bu nedenle çağrı 404 hatasıyla döner ve model asla çalışmaz. Bu sonek, OpenAI uyumlu arayüzün bir parçasıdır, süsleme değildir.

Ollama farklı bir makinede çalışıyorsa, o makinenin adresi temel URL olur ve istemleriniz ağ üzerinden şifrelenmemiş düz HTTP ile iletilir. Ollama'yı aynı sunucuda tutun veya TLS (taşıma katmanı güvenliği) ve kimlik doğrulama arkasına alın: açıkta kalan bir Ollama uç noktasını güvenli hale getirme.

Her modda makineden dışarı giden veriler

Bir DeepSeek anahtarı kullanıldığında, her istek DeepSeek API'sine gönderilir. Bu istek; isteminizi, temsilcinin (agent) yanıt vermek için okuduğu dosyaların içeriğini, çalıştırdığı komutların çıktılarını ve dahil etmeyi seçtiği tüm araç sonuçlarını taşır. Temsilci bir dosyayı açtığında, kaynak kodunuz bu veri yükünün içinde yer alır. Barındırılan (hosted) bir model bu şekilde çalışır; temsilciyi hangi dizinde başlattığınızı düşünmenizin nedeni de budur.

Başka bir katalog sağlayıcısı veya şirket ağ geçidi kullanıldığında, aynı veri yükü ilgili satıcıya iletilir. Temel URL (base URL), verinin tam olarak nereye gittiğini belirtir.

Yerel bir uç nokta (local endpoint) kullanıldığında, model isteği 127.0.0.1:11434 adresine gider ve makinede kalır. Kodunuzun hiçbir parçası bir model satıcısına ulaşmaz. Yine de üç tür veri ağ üzerinden iletilir: npx, paketi npm kayıt defterinden indirir. Temsilcinin çalıştırdığı herhangi bir araç, bağladığınız MCP (model context protocol) sunucuları dahil olmak üzere internete kendi başına erişebilir; bu konu running MCP servers on a VPS bölümünde ayrıntılı olarak ele alınmıştır. Ayrıca, etkinleştirirseniz telemetri verileri de gönderilir.

Telemetri, siz onay verene kadar kapalıdır. DSH_TELEMETRY_MODE onay anahtarıdır; ayarlanmamış, boş veya tanınmayan değerler DISABLED olarak kabul edilir. Bu durumda dsh herhangi bir OpenTelemetry (OTel) sağlayıcısı, işlemcisi veya dışa aktarıcısı oluşturmaz; dolayısıyla yeni bir profil hiçbir telemetri ağ isteğinde bulunmaz. FEEDBACK_ONLY, geri bildirim tetiklemeli oturum günlüğü paylaşımına onay verir. FULL ise başlatıcı raporlamasına izin verir. Oturum akışı; oturum içeriğini, araç verilerini, istemleri ve çalışma alanı yollarını dışa aktarabilir, bu nedenle FULL ayarını çalışmalarınızı DeepSeek'e göndermek olarak değerlendirin.

Mod dizgisini doğru ayarlamaya bağlı olmayan kesin bir durdurma için DSH_TELEMETRY_DISABLED=1 ayarını yapılandırın. Boş olmayan herhangi bir değer yetkili bir devre dışı bırakma (opt-out) işlemidir ve çalışma başlamadan önce okunduğu için proje kodu oturum sırasında bunu tekrar açamaz. Varsayılan toplayıcı adresi harness-telemetry.deepseeksvc.com'dir; bu adres, kendi güvenlik duvarı günlüklerinizi incelerken bilmeniz gereken yararlı bir isimdir.

Ayara güvenmek yerine doğrulama yapın. Bir görev çalışırken, sürecin tuttuğu giden bağlantıları listeleyin.

sudo ss -tnp | grep -i node

Yerel model modunda, 11434 numaralı porta yapılan loopback bağlantısını görmeli ve genel bir adrese bağlantı görmemelisiniz. Bunun dışındaki herhangi bir durum, devam etmeden önce tanımlanmalıdır. What a coding agent sends home bölümü, aynı kontrolü diğer araçlar üzerinde gerçekleştirir ve sonucun nasıl okunacağını açıklar.

Gizli bilgilerin bulunmaması gereken yerler

• Shell geçmişi. export DEEPSEEK_API_KEY=sk-..., ~/.bash_history dosyasına düz metin olarak yazılır ve anahtarı rotasyona tabi tutsanız bile orada uzun süre kalır. HISTCONTROL=ignorespace ayarlandığında komutun başına bir boşluk ekleyin veya shell kullanmak yerine değeri doğrudan 600 izinli bir dosyaya yazın.
• Commit edilmiş dotfile dosyaları. Dotfile dosyalarınızı git üzerinde tutuyorsanız, ~/.bashrc veya ~/.zshrc içindeki bir anahtar, tek bir git add ile herkese açık bir depoya sızabilir. Push işleminden önce ilgili depoda git grep -I -n 'sk-' çalıştırın.
• settings.yaml. Özel sağlayıcılar için apiKeyEnv kullanın; böylece dosya gizli bilgi yerine bir değişken adı tutar. Yapılandırma dosyaları hata raporlarına ve destek sohbetlerine yapıştırılır. Kimlik bilgisi dosyaları ise yapıştırılmamalıdır.
• env çıktısı ve terminal ekran görüntüleri. Tüm ortam değişkenlerini yazdıran her komut, anahtarı da beraberinde yazdırır.
• Yedekler. ~/.dsh yedeklenmeye değerdir ancak içindeki .credentials.yaml canlı bir gizli bilgidir. Bu dosyayı yedekleme kapsamı dışında tutun veya arşivi şifreleyin.

Bu kurallar yalnızca dsh ile sınırlı değildir; gizli bilgileri Compose env dosyalarından uzak tutmak konusu, aynı sunucunun container tarafındaki benzer sorunu ele almaktadır.

Geliştirici önizleme sürümü ile çalışmak

Test ettiğiniz sürümü sabitleyin; çünkü bir önizleme sürümü, yama güncellemesiyle bir yapılandırma anahtarını değiştirebilir ve bu durumda sağlayıcınız yükleme yapamaz. settings.yaml ve cordis.patch.yml dosyalarını, kimlik bilgileri dosyasını hariç tutarak sürüm kontrolünde tutun; böylece bir yükseltmeden sonra nelerin değiştiğini görebilirsiniz.

Bir profil düzgün çalışmadığında iki bayrak yardımcı olur. --dump-default-config, sistemi başlatmadan oluşturulan varsayılan yapılandırmayı yazdırır; --dump-config ise profiliniz için oluşturulan yapılandırmayı aynı şekilde yazdırır. İkisini karşılaştırmak, yama katmanınızın gerçekte neleri değiştirdiğini gösterir; bu yöntem, katmanları manuel olarak okumaktan daha hızlıdır.

dsh --profile web --dump-config

Bir yükseltmeden sonra bir şeyler bozulduğunda, önce bunu çalıştırın. Sürümler arasında yeri değişen bir anahtar, döküm içinde eksik bir dal olarak görünür ve düzeltme, yeniden kurulum yerine tek satırlık bir düzenlemeden ibarettir.

FAQ

dsh, DeepSeek API anahtarımı nerede saklar?

$DSH_HOME/.credentials.yaml dizininde saklar; siz DSH_HOME değişkenini kendiniz ayarlamadığınız sürece bu dizin ~/.dsh/.credentials.yaml konumundadır. Modeller sayfası anahtarı buraya yazar ve ayarlarınız yalnızca bu dosyaya bir referans tutar; böylece gizli veri tek bir dosyada kalır. Dosya izinlerini stat -c '%a %n' ~/.dsh/.credentials.yaml ile kontrol edin ve izinler daha gevşekse 600 olarak ayarlayın. Özel bir sağlayıcı kullanıyorsanız, apiKeyEnv ile bir ortam değişkeni tanımlayarak dosya kullanımını tamamen devre dışı bırakabilirsiniz.

dsh'in DeepSeek API yerine yerel bir model kullanmasını nasıl sağlarım?

Temel URL'si yerel OpenAI uyumlu uç noktanız olan özel bir sağlayıcı ekleyin. Ollama için bu adres http://127.0.0.1:11434/v1'dur; api: openai-completions ve ollama list çıktısından tam olarak kopyalanmış bir id model adı kullanın. Ollama bir API anahtarı değeri gerektirir ancak bu değeri dikkate almaz, bu nedenle boş olmayan herhangi bir karakter dizisi çalışacaktır. dsh yapılandırmasını düzenlemeden önce uç noktanın curl -s http://127.0.0.1:11434/v1/models ile yanıt verdiğini doğrulayın; çünkü çalışmayan bir uç nokta ile hatalı bir yapılandırma benzer hata mesajları üretir.

dsh varsayılan olarak kodumu herhangi bir yere gönderir mi?

Barındırılan bir model kullanıyorsanız, evet. İsteminiz ve ajanın okuduğu dosyaların içeriği, ilgili sağlayıcıya yapılan API isteğinin bir parçasıdır. Yerel bir uç nokta kullanıldığında, bu istek loopback arayüzüne gider ve makinede kalır. Telemetri ayrı bir veri akışıdır ve varsayılan olarak kapalıdır: DSH_TELEMETRY_MODE ayarlanmadığında DISABLED değerini alır ve bu durumda hiçbir dışa aktarıcı oluşturulmaz. Çalışma başlamadan önce devre dışı bırakma tercihi için DSH_TELEMETRY_DISABLED=1 değişkenini ayarlayın.

Değişkenim ayarlı olmasına rağmen dsh neden MISSING_CREDENTIAL hatası veriyor?

Çünkü dsh, apiKeyEnv tarafından belirtilen değişkeni kendi süreç ortamından okur. Shell içerisinde dışa aktarılan (export) bir değişken; bir systemd servisine, farklı bir kullanıcının oturumuna veya siz dışa aktarma işlemini yapmadan önce başlatılmış bir sürece ulaşmaz. Değeri, birim (unit) için 600 izinlerine sahip bir EnvironmentFile dosyasına koyun veya dsh'i başlatan aynı shell içerisinde dışa aktarın. Çalışan sürecin gerçekte hangi değerleri tuttuğunu sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ ile doğrulayın.

dsh hangi Node.js sürümüne ihtiyaç duyar?

Node.js 22 serisinde 22.19 veya üzeri ya da 24 ve üzeri sürümler gereklidir. Node 23 desteklenen aralığın dışındadır. Başka bir işlem yapmadan önce node -v komutunu çalıştırın; çünkü desteklenmeyen bir çalışma zamanından kaynaklanan başlatma hatası, bozuk bir kurulum gibi görünür ve kullanıcıların çalışma zamanı yerine paketi yeniden yüklemeye çalışmasına neden olur.