dsh yapılandırması nasıl yapılır ve API anahtarı eklenir

dsh yapılandırmasını nerede tutar

dsh (DeepSeek Harness), yapılandırmasını tek bir dizinde tutar: $DSH_HOME; bu dizin varsayılan olarak ~/.dsh konumundadır. Web arayüzü üzerinden yaptığınız tüm ayarlar burada düz metin dosyaları olarak yazılır. Bu dizini başka bir sunucuya kopyaladığınızda, yeni sunucu eski sunucuyla 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 bir kimlik bilgisine referans tutar, 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, harness'ı 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 eşleşmektedir. Bir önizleme sürümü sürümler arasında isimlendirmeleri değiştirebileceğinden, herhangi bir kılavuzdan (bu kılavuz dahil) yapılandırma kopyalamadan önce bunları kurduğunuz sürüme ait belgelerle karşılaştırın.

İlk çalıştırma için gereken asgari işlemler

dsh, Node.js 22.19 veya sonraki 22.x sürümlerini ya da 24 ve üzeri sürümleri gerektirir. Node 23 bu aralığın dışındadır. Sürümü öncelikle kontrol edin; sürüm uyuşmazlığı başlangıçta başarısızlığa yol açar ve hata mesajı bozuk bir paket izlenimi verir.

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 dahi port başka bir makineden erişilebilir olmaz. Bir VPS üzerinde, 3080 numaralı portu internete açmak yerine SSH üzerinden yönlendirin. Eğer ekrana yazdırılan URL kafa karıştırıcıysa, dsh neden bu adreste başlar belgesi, loopback bağlantısının neyi koruyup neyi korumadığını açıklar.

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 anlık olarak çözümlediği ve sakladığı için, herhangi bir yeniden başlatmaya gerek kalmadan model yolu hemen kullanılabilir hale gelir. Uzak bir sunucudaki dsh Web arayüzüne erişim tünelleme ve reverse proxy durumlarını, DeepSeek Harness kurulumu ise bu kılavuzun varsaydığı sunucu hazırlıklarını kapsar.

Kaydettikten sonra uygulamanın oluşturduğu dosyaları 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 erişilebilir 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 profil tek bir oturum çalıştırır ve nihai yanıtı ekrana yazdırır.

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

dsh uygulaması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ı Models 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ü, kaydettikten sonra anahtarı bir daha asla göstermez.

Özel bir sağlayıcı ise bunun yerine apiKeyEnv ile bir ortam değişkeni belirtebilir. Dokümantasyonun ~/.dsh/settings.yaml için sunduğu biçim budur.

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 önizleme aşaması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 tarafından görülmez; 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ıya ait olacak şekilde 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 bildirmek 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 şekilde yapılandırılamaz; bu nedenle, bu rotaya eklenen bir görüntü, herhangi bir veri gönderilmeden önce reddedilir.

Kodunuzun sunucuda kalması için dsh aracını yerel bir uç noktaya yönlendirin

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. Önce model sunucusunu kurun: Ollama ile bir VPS üzerinde LLM self-hosting 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, Ollama'nın çalışmadığını veya 11434 numaralı portu dinlemediğini gösterir.

Ş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 işlemdeki hataların neredeyse tamamı üç nedenden kaynaklanı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ği anlamına gelir; bu nedenle değeri, iki noktadan sonraki etiket dahil olmak üzere ollama list ile karakter karakter karşılaştırın. Mevcut modeller getirilirken 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 düz HTTP ile şifrelenmemiş olarak iletilir. Ollama'yı aynı ana makinede tutun veya TLS (taşıma katmanı güvenliği) ve kimlik doğrulama arkasına alın: açık 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, ajanın 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. Ajan bir dosyayı açtığında, kaynak kodunuz bu veri yükünün içinde yer alır. Barındırılan (hosted) bir modelin çalışma mantığı budur ve ajanı hangi dizinde başlatacağı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ü bunun yerine ilgili satıcıya gider. 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. Ajanın çalıştırdığı herhangi bir araç, bağladığınız MCP (model context protocol) sunucuları dahil olmak üzere kendi başına internete erişebilir; bu konu VPS üzerinde MCP sunucuları çalıştırma bölümünde ayrıntılı olarak ele alınmıştır. Bir eklenti de aynı kategoriye girer; çünkü bir eklenti yüklemek, başka bir yazarın kodunu ajanın izinleriyle çalıştırmak anlamına gelir, bu nedenle bir eklentiyi yüklemeden önce nelere erişebileceğini kontrol etmek önemlidir. 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ı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, kendi güvenlik duvarı günlüklerinizi okurken 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ı bağlantı noktasına giden bir loopback bağlantısı görmeli ve genel bir adrese giden hiçbir bağlantı görmemelisiniz. Başka herhangi bir bağlantı, devam etmeden önce tanımlanmalıdır. Bir kodlama ajanı merkeze ne gönderir bölümü, diğer araçlar için aynı kontrolü gerçekleştirir ve sonucun nasıl okunacağını açıklar.

Gizli verilerin 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 kullanmayı atlayıp değeri doğrudan 600 moduna sahip bir dosyaya yazın.
• Commit edilmiş dotfile dosyaları. Dotfile dosyalarınızı git üzerinde tutuyorsanız, ~/.bashrc veya ~/.zshrc içindeki bir anahtar, halka açık bir depoya sadece bir git add uzaklıktadır. Push işlemini yapmadan önce o depoda git grep -I -n 'sk-' komutunu çalıştırın.
• settings.yaml. Özel sağlayıcılar için apiKeyEnv kullanın; böylece dosya gizli veri 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ılmaz.
• env çıktısı ve terminal ekran görüntüleri. Tüm ortamı yazdıran her şey, anahtarı da beraberinde yazdırır.
• Yedekler. ~/.dsh yedeklenmeye değerdir ve içindeki .credentials.yaml canlı bir gizli veridir. Bu dosyayı hariç tutun veya arşivi şifreleyin.

Bu kurallar sadece dsh için geçerli değildir; Compose env dosyalarından gizli verileri uzak tutmak konusu, aynı sunucunun container tarafındaki benzer sorunu ele almaktadır.

Developer preview ile çalışmak

Test ettiğiniz sürümü sabitleyin; çünkü bir preview sürümü, bir yama sürümünde yapılandırma anahtarını değiştirebilir ve bu durumda sağlayıcınız yükleme yapamaz. Sabitlenmiş kurulum buna rağmen başlamayı reddederse veya npx size talep etmediğiniz bir derleme sunmaya devam ederse, bir preview sürümünün ürettiği kurulum ve sürüm hataları bölümü, npx önbelleğini ve Node ile birlikte gelen npm sürümünü ele almaktadır. 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ştirilen 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?

Anahtar, DSH_HOME değişkenini kendiniz ayarlamadığınız sürece ~/.dsh/.credentials.yaml olan $DSH_HOME/.credentials.yaml dosyasında saklanır. Modeller sayfası anahtarı buraya yazar ve ayarlarınız yalnızca bu dosyaya bir referans tutar; böylece gizli veri tek bir dosyada toplanmış olur. 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'ın 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 olup, api: openai-completions ve ollama list içinden tam olarak kopyalanmış bir id model adı kullanılmalıdır. Ollama bir API anahtarı değeri gerektirir ancak bu değeri dikkate almaz, bu nedenle boş olmayan herhangi bir karakter dizisi çalışacaktır. Herhangi bir 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 çıktıları üretir.

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

Barındırılan (hosted) bir model kullanıyorsanız, evet. İsteminiz (prompt) ve aracı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 ise bu istek loopback üzerinden iletilir 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ı (exporter) oluşturulmaz. Çalışma başlamadan önce devre dışı bırakma işlemi için DSH_TELEMETRY_DISABLED=1 değerini 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'inizde dışa aktardığınız (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'ı başlatan aynı shell içinde 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ı, kurulumun bozuk olduğu izlenimini vererek kullanıcıların çalışma zamanı yerine paketi yeniden yüklemeye çalışmasına neden olur.