dsh-এ API key, model ও endpoint সেটআপ

dsh যেখানে configuration সংরক্ষণ করে

dsh (DeepSeek Harness) তার configuration একটি directory-তে সংরক্ষণ করে: $DSH_HOME, যার default হলো ~/.dsh। Web UI-তে আপনি যা সেট করেন, তা সেখানে plain file হিসেবে লেখা হয়। ওই directory অন্য server-এ copy করলে নতুন server-টি পুরোনোটির মতোই কাজ করবে।

আপনি যে চারটি path নিয়ে কাজ করবেন, সেগুলোতেই সব configuration থাকে।

• ~/.dsh/settings.yaml-এ হাতে লেখা এবং UI-তে লেখা settings থাকে, যার মধ্যে provider ও model route-ও রয়েছে।
• ~/.dsh/.credentials.yaml-এ secrets থাকে। Settings-এ credential-এর শুধু reference সংরক্ষিত হয়, তাই key value নিজেই একটি file-এ থাকে।
• ~/.dsh/profiles/-এ named profile এবং ~/.dsh/storages/-এ saved session থাকে।
• ~/.dsh/cordis.patch.yml আপনার নিজস্ব patch layer। এটি প্রতিটি profile-এর জন্য built-in configuration-এর ওপর প্রয়োগ করা হয়।

DeepSeek 17 August 2026-এ harness-টিকে MIT-licensed developer preview হিসেবে ঘোষণা করেছে, এবং README-তে বলা হয়েছে যে compatibility-breaking পরিবর্তন হবে। এই guide-এ ব্যবহৃত field name ও path-গুলো August 2026 পর্যন্ত repository documentation-এর সঙ্গে মেলে। এই guide-সহ যেকোনো guide থেকে configuration copy করার আগে আপনার installed version-এর documentation-এর সঙ্গে এগুলো মিলিয়ে নিন, কারণ preview release-গুলোর মধ্যে path ও field name পরিবর্তিত হতে পারে।

প্রথম output পাওয়ার জন্য প্রকৃত ন্যূনতম সেটআপ

dsh চালাতে 22 সিরিজের Node.js 22.19 বা পরবর্তী সংস্করণ, অথবা 24 বা তার পরের সংস্করণ প্রয়োজন। Node 23 এই সীমার বাইরে। প্রথমে সংস্করণ পরীক্ষা করুন, কারণ সংস্করণ না মিললে startup-এর সময় ব্যর্থতা ঘটে এবং error message দেখে মনে হতে পারে package নষ্ট হয়েছে।

node -v
npx @deepseek-ai/dsh web

npx npm registry থেকে package download করে http://127.0.0.1:3080-এ Web UI চালু করে। এটি loopback address-এ bind হয়। তাই firewall অনুমতি দিলেও অন্য কোনো machine থেকে port-এ পৌঁছানো যায় না। VPS-এ 3080 Internet-এর জন্য খুলে না দিয়ে SSH-এর মাধ্যমে forward করুন। মুদ্রিত URL-টি বিভ্রান্তিকর হলে dsh কেন ওই address-এ চালু হয় শিরোনামের ব্যাখ্যায় loopback bind কী সুরক্ষা দেয় এবং কী দেয় না, তা দেখানো হয়েছে।

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

আপনার laptop-এ http://127.0.0.1:3080 খুলুন। এরপর Settings এবং Models-এ যান। DeepSeek card-এ একটি API key field আছে। platform.deepseek.com থেকে key কপি করে এখানে paste করুন এবং save করুন। কোনো restart ছাড়াই model route সঙ্গে সঙ্গে ব্যবহারযোগ্য হয়ে যায়, কারণ চলমান server credential সংরক্ষণ করে এবং reference-টি runtime-এ resolve করে। Remote server-এ dsh Web UI-তে পৌঁছানো অংশে tunnel এবং reverse proxy ব্যবহারের বিষয়টি ব্যাখ্যা করা হয়েছে। VPS-এ DeepSeek Harness install করা অংশে এই guide-এ ধরে নেওয়া server preparation দেখানো হয়েছে।

save করার পরে app কী তৈরি করেছে তা দেখুন।

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

আপনার settings.yaml, .credentials.yaml এবং profiles/ দেখতে পাওয়ার কথা। stat যদি 600 ছাড়া অন্য কোনো mode দেখায়, তাহলে chmod 600 ~/.dsh/.credentials.yaml চালান। group-readable বা world-readable credentials file থাকলে server-এর অন্য প্রতিটি account আপনার key পেয়ে যেতে পারে।

browser ছাড়া প্রথমবার চালানোর জন্য একটি command-ই যথেষ্ট।

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

headless profile একটি single session চালায় এবং চূড়ান্ত answer print করে।

পরিবেশ ভেরিয়েবল অথবা config file

dsh-কে key দেওয়ার 2টি উপায় আছে। এগুলো পরস্পরের বিকল্প নয়।

একটি catalog provider (DeepSeek, Anthropic, OpenAI এবং built-in list-এর অন্যান্য provider) Models page-এর মাধ্যমে key গ্রহণ করে। মানটি ~/.dsh/.credentials.yaml-এ সংরক্ষিত হয়, আর আপনার settings-এ শুধু তার reference থাকে। সংরক্ষণ করার পরে Web UI আর key দেখায় না।

একটি custom provider-এর ক্ষেত্রে apiKeyEnv ব্যবহার করে environment variable-এর নাম দেওয়া যায়। ~/.dsh/settings.yaml-এর জন্য documentation-এ এই কাঠামোটিই দেওয়া আছে।

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]

প্রথমে Web UI-এর মাধ্যমে একটি provider যোগ করুন। এরপর ~/.dsh/settings.yaml খুলে সেখানে লেখা কাঠামোটি কপি করুন। Developer preview চলাকালে nesting পরিবর্তিত হওয়ার সম্ভাবনাই সবচেয়ে বেশি। অ্যাপ যে file-টি এইমাত্র লিখেছে, সেটিই সবসময় বর্তমান কাঠামো দেখায়।

apiKeyEnv dsh process-এর environment থেকে পড়া হয়, আপনার login shell থেকে নয়। একটি interactive session-এ export করা key systemd unit-এর কাছে দৃশ্যমান নয়। তাই হাতে dsh web লিখে যে config কাজ করে, service হিসেবে চললে একই config MISSING_CREDENTIAL ফেরত দেয়। Unit-এর জন্য আলাদা file ব্যবহার করুন।

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

File-টির mode 600 রাখুন। File-টির মালিকানা service যে user হিসেবে চলে, সেই user-এর নামে সেট করুন।

মডেল নির্বাচন এবং যে ID-এর নাম পরিবর্তন করা যায় না

কনফিগার করা প্রতিটি provider model picker-এ দেখা যায়। কোনো model নির্বাচন করলে নতুন session-এর জন্য সেটিই default হয়। আগে থেকে থাকা session-এ যে model-এর তথ্য সংরক্ষিত আছে, সেটিই থাকে; তাই model পরিবর্তন করলে পুরোনো conversation নতুন করে লেখা হয় না।

Provider ID স্থায়ী। Request, সংরক্ষিত session, model default এবং credential reference—সবই এই ID-কে নির্দেশ করে। তাই ID পরিবর্তনের কোনো rename button নেই। এটি পরিবর্তন করতে হলে নতুন provider তৈরি করে পুরোনোটি মুছে ফেলতে হবে। এমন একটি নাম বেছে নিন যা পরে পরিবর্তন করার প্রয়োজন হবে না: local-ollama-এর পরিবর্তে test2।

আপনি আলাদাভাবে উল্লেখ না করলে model শুধু text সমর্থন করে। কোনো model entry-তে image support ঘোষণা করতে input: [text, image] যোগ করুন। অথবা catalog-এ যেসব model-এর সমর্থন বর্ণনা করা নেই, সেগুলোর জন্য fallback হিসেবে route level-এ defaultInput সেট করুন। DeepSeek-এর নিজস্ব chat-completions route শুধু text সমর্থন করে এবং অন্যভাবে configure করা যায় না। তাই ওই route-এ সংযুক্ত image কোনো data পাঠানোর আগেই প্রত্যাখ্যাত হয়।

স্থানীয় endpoint-এ dsh নির্দেশ করুন, যাতে আপনার code একই server-এ থাকে

Ollama http://127.0.0.1:11434/v1-এ OpenAI-compatible API সরবরাহ করে। dsh custom provider-এর মাধ্যমে যেকোনো OpenAI-compatible base URL-এ সংযোগ করতে পারে, তাই মাঝখানে আর কোনো স্তরের প্রয়োজন হয় না। প্রথমে model server সেট আপ করুন: VPS-এ Ollama দিয়ে LLM self-host করা-এ installation এবং model pull করার পদ্ধতি দেওয়া আছে।

dsh-এ পরিবর্তন করার আগে endpoint সাড়া দিচ্ছে কি না নিশ্চিত করুন।

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

ollama list আপনার pull করা প্রতিটি model-এর সঠিক tag দেখায়। সেই string কপি করুন। curl একই model-গুলো JSON হিসেবে ফেরত দেয়। খালি list-এর অর্থ হলো Ollama চলছে, কিন্তু কোনো model pull করা নেই। Connection refused-এর অর্থ হলো Ollama চলছে না, অথবা 11434-এ listening করছে না।

এখন provider যোগ করুন। Ollama একটি API key field প্রয়োজন করে, তবে এর মান উপেক্ষা করে। তাই যেকোনো non-empty string কাজ করবে।

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>

dsh process যেখানে variable-টি দেখতে পাবে, সেখানে এটি export করুন।

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

প্রায় সব প্রচেষ্টার ব্যর্থতা তিনটি বিষয় দিয়ে ব্যাখ্যা করা যায়। MISSING_CREDENTIAL-এর অর্থ হলো dsh apiKeyEnv-এর নামে উল্লেখ করা variable পড়তে পারেনি। তাই আপনার terminal-এর environment নয়, process-এর environment পরীক্ষা করুন। UNKNOWN_MODEL-এর অর্থ হলো id-এর মান কোনো configured model-এর সঙ্গে মেলে না। তাই ollama list-এর সঙ্গে character-by-character তুলনা করুন, colon-এর পরের tag-সহ। available model আনতে গিয়ে 401 error হলে তা model discovery থেকে এসেছে। এই প্রক্রিয়ায় আপনার base URL-এ GET /models কল করা হয়। যেসব endpoint এই path সরবরাহ করে না, সেসব ক্ষেত্রে model-গুলোর নাম হাতে লিখে দিতে হবে।

base URL নিয়েও একটি সাধারণ সমস্যা আছে। এর শেষে /v1 বাদ দিলে request এমন path-এ যায়, যা Ollama সরবরাহ করে না। ফলে call 404 error ফেরত দেয় এবং model চালু হয় না। এই suffix OpenAI-compatible surface-এর অংশ; এটি শুধু আনুষ্ঠানিক লেখা নয়।

Ollama অন্য machine-এ চললে সেই machine-এর address base URL হবে। তখন আপনার prompt plain HTTP-এর মাধ্যমে cleartext-এ network পার হবে। একই host-এ Ollama চালান, অথবা এটিকে TLS (transport layer security) ও authentication-এর পেছনে রাখুন: exposed Ollama endpoint সুরক্ষিত করা।

প্রতিটি মোডে মেশিন থেকে কী বের হয়

DeepSeek key ব্যবহার করলে প্রতিটি request DeepSeek-এর API-তে যায়। সেই request-এর সঙ্গে আপনার prompt, agent যে file পড়ে উত্তর তৈরি করেছে তার content, agent চালানো command-এর output এবং অন্তর্ভুক্ত করার জন্য বেছে নেওয়া tool result পাঠানো হয়। Agent কোনো file খুললে আপনার source code-ও সেই payload-এর অংশ হয়। Hosted model এভাবেই কাজ করে। তাই agent কোন directory থেকে শুরু করছেন, তা বিবেচনা করা জরুরি।

অন্য কোনো catalog provider বা company gateway ব্যবহার করলে একই payload সেই vendor-এর কাছে যায়। Base URL দেখলেই ঠিক কোথায় যাচ্ছে তা জানা যায়।

Local endpoint ব্যবহার করলে model request 127.0.0.1:11434-এ যায় এবং একই machine-এ থাকে। আপনার code-এর কোনো অংশ model vendor-এর কাছে পৌঁছায় না। তবে 3টি জিনিস network পেরোয়। npx npm registry থেকে package download করে। Agent যে কোনো tool চালালে সেটি নিজের মতো করে Internet-এ পৌঁছাতে পারে। এর মধ্যে আপনার সংযুক্ত MCP (model context protocol) server-ও রয়েছে। এ বিষয়ে VPS-এ MCP server চালানো বিস্তারিত ব্যাখ্যা করে। Plugin-ও একই শ্রেণির, কারণ plugin install করলে আপনার agent-এর permission নিয়ে অন্য লেখকের code চালানো হয়। তাই install করার আগে plugin কী কী access করতে পারে তা যাচাই করা উপযোগী। Telemetry চালু করলে সেটিও network পেরোয়।

আপনি opt in না করা পর্যন্ত telemetry বন্ধ থাকে। DSH_TELEMETRY_MODE হলো consent switch। unset, empty বা unrecognised value হলে সেটি DISABLED হিসেবে গণ্য হয়। এই অবস্থায় dsh কোনো OpenTelemetry (OTel) provider, processor বা exporter তৈরি করে না। তাই নতুন profile থেকে কোনো telemetry network request যায় না। FEEDBACK_ONLY feedback-triggered session log sharing চালু করে। FULL launcher reporting-ও অনুমোদন করে। Session feed session content, tool data, prompt এবং workspace path export করতে পারে। তাই FULL-কে আপনার কাজ DeepSeek-এর কাছে পাঠানো হিসেবে বিবেচনা করুন।

Mode string সঠিকভাবে সেট করার ওপর নির্ভর না করে সম্পূর্ণভাবে বন্ধ করতে DSH_TELEMETRY_DISABLED=1 সেট করুন। যেকোনো non-empty value authoritative opt-out হিসেবে কাজ করে। Run শুরু হওয়ার আগেই এটি পড়া হয়, তাই project code session চলাকালে এটি আবার চালু করতে পারে না। Default collector address হলো harness-telemetry.deepseeksvc.com। নিজের firewall log পড়ার সময় এই নামটি জানা উপযোগী।

Setting-এর ওপর নির্ভর না করে যাচাই করুন। কোনো task চলার সময় process-টি যেসব outbound connection ধরে রেখেছে, সেগুলোর তালিকা দেখুন।

sudo ss -tnp | grep -i node

Local-model mode-এ loopback connection to 11434 দেখা উচিত এবং কোনো public address-এর সঙ্গে connection থাকা উচিত নয়। অন্য কিছু দেখা গেলে চালিয়ে যাওয়ার আগে সেটি শনাক্ত করুন। Coding agent কী কী data বাইরে পাঠায় একই পরীক্ষা অন্য harness-এর বিরুদ্ধে চালায় এবং ফলাফল কীভাবে পড়তে হয় তা ব্যাখ্যা করে।

যেখানে secret রাখা উচিত নয়

• Shell history। `export DEEPSEEK_API_KEY=sk-... cleartext-এ ~/.bash_history-এ লেখা হয় এবং key rotate করার অনেক পরেও সেখানে থেকে যায়। HISTCONTROL=ignorespace` সেট করা থাকলে command-এর শুরুতে একটি space দিন, অথবা shell এড়িয়ে value সরাসরি mode 600-সহ একটি file-এ লিখুন।
• Commit করা dotfile। dotfile git-এ রাখলে `~/.bashrc বা ~/.zshrc-এ থাকা একটি key public repository-তে প্রকাশের জন্য মাত্র git add দূরে থাকে। push করার আগে ওই repository-তে git grep -I -n 'sk-'` চালান।
• `settings.yaml। custom provider-এর জন্য apiKeyEnv` ব্যবহার করুন, যাতে file-এ secret-এর বদলে একটি variable name থাকে। Config file issue report এবং support chat-এ paste হয়ে যায়। Credentials file সাধারণত paste করা হয় না।
• `env`-এর output এবং terminal screenshot। পুরো environment print করে এমন যেকোনো command key-টিও দেখায়।
• Backup। `~/.dsh backup করা গুরুত্বপূর্ণ, কিন্তু এর ভেতরের .credentials.yaml` একটি সক্রিয় secret। ওই file বাদ দিন, অথবা archive encrypt করুন।

এই নিয়মগুলো শুধু dsh-এর জন্য নয়। একই server-এর container দিকের একই সমস্যা Compose env file-এর বাইরে secret রাখা-এ ব্যাখ্যা করা হয়েছে।

Developer preview ব্যবহার করে কাজ করা

আপনি যে version পরীক্ষা করেছেন, সেটি pin করুন। কারণ একটি preview patch release-এ config key পরিবর্তন করতে পারে, ফলে আপনার provider load করতে ব্যর্থ হতে পারে। pinned install start হতে অস্বীকার করলে, অথবা npx বারবার আপনার চাওয়া build-এর বদলে অন্য build সরবরাহ করলে, preview থেকে তৈরি install ও version error-এ npx cache এবং আপনার Node-এর সঙ্গে আসা npm সম্পর্কে ব্যাখ্যা আছে। credentials file বাদ দিয়ে settings.yaml এবং cordis.patch.yml version control-এ রাখুন। এতে upgrade-এর পরে কী পরিবর্তিত হয়েছে তা দেখা যায়।

কোনো profile প্রত্যাশামতো কাজ না করলে দুটি flag সহায়ক। --dump-default-config boot না করেই composed default configuration দেখায়। --dump-config একইভাবে আপনার profile-এর জন্য composed configuration দেখায়। দুটি output তুলনা করলে আপনার patch layer আসলে কী পরিবর্তন করেছে তা বোঝা যায়। প্রতিটি layer হাতে পড়ার চেয়ে এটি দ্রুত।

dsh --profile web --dump-config

upgrade-এর পরে কোনো কিছু নষ্ট হলে প্রথমে এটি চালান। releases-এর মধ্যে কোনো key সরানো হলে dump-এ সেটি missing branch হিসেবে দেখা যায়। তখন reinstall না করে এক লাইনের edit করলেই সমস্যা ঠিক করা যায়।

FAQ

আমার DeepSeek API key কোথায় dsh সংরক্ষণ করে?

$DSH_HOME/.credentials.yaml-এ, যা আপনি নিজে DSH_HOME সেট না করলে ~/.dsh/.credentials.yaml। Models page সেখানে key লিখে রাখে, আর আপনার settings-এ শুধু সেই key-এর reference থাকে। তাই secret একটি ফাইলেই থাকে। stat -c '%a %n' ~/.dsh/.credentials.yaml দিয়ে mode পরীক্ষা করুন এবং mode 600-এর চেয়ে বেশি উন্মুক্ত হলে 600 সেট করুন। apiKeyEnv দিয়ে একটি environment variable-এর নাম নির্ধারণ করলে custom provider ফাইলটি সম্পূর্ণ এড়াতে পারে।

DeepSeek API-এর পরিবর্তে dsh-কে local model ব্যবহার করাব কীভাবে?

আপনার local OpenAI-compatible endpoint-এর base URL ব্যবহার করে একটি custom provider যোগ করুন। Ollama-এর ক্ষেত্রে সেটি http://127.0.0.1:11434/v1, যেখানে api: openai-completions এবং id-এর model name ollama list থেকে হুবহু কপি করতে হবে। Ollama একটি API key value চায়, কিন্তু সেটি উপেক্ষা করে। তাই যেকোনো non-empty string কাজ করবে। dsh-এর configuration সম্পাদনা করার আগে curl -s http://127.0.0.1:11434/v1/models দিয়ে endpoint-এর উত্তর পরীক্ষা করুন। কারণ endpoint অচল থাকা এবং ভুল configuration থেকে একই ধরনের error দেখা যেতে পারে।

dsh কি ডিফল্টভাবে আমার code কোথাও পাঠায়?

Hosted model ব্যবহার করলে পাঠায়। আপনার prompt এবং agent যে file-গুলোর contents পড়েছে, সেগুলো vendor-এর API request-এর অংশ থাকে। Local endpoint ব্যবহার করলে requestটি loopback-এ যায় এবং মেশিনের মধ্যেই থাকে। Telemetry আলাদা feed এবং এটি ডিফল্টভাবে বন্ধ থাকে: DSH_TELEMETRY_MODE unset থাকলে DISABLED-এ resolve হয়, এবং সেই অবস্থায় কোনো exporter তৈরি হয় না। Run শুরু হওয়ার আগে পড়া হয় এমন opt-out সেট করতে DSH_TELEMETRY_DISABLED=1 নির্ধারণ করুন।

আমার variable সেট করা থাকা সত্ত্বেও dsh কেন MISSING_CREDENTIAL দেখায়?

কারণ dsh apiKeyEnv-এর নাম দেওয়া variable-টি নিজের process environment থেকে পড়ে। আপনার shell-এ export করা variable systemd service, অন্য user-এর session বা export করার আগে শুরু হওয়া process-এ পৌঁছায় না। Unit-এর জন্য mode 600-সহ একটি EnvironmentFile-এ value রাখুন, অথবা dsh যে একই shell থেকে শুরু করছেন সেখানে variableটি export করুন। চলমান process আসলে কী value ধরে রেখেছে, তা sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ দিয়ে নিশ্চিত করুন।

dsh-এর জন্য কোন Node.js version প্রয়োজন?

22 line-এর জন্য Node.js 22.19 বা পরবর্তী version, অথবা 24 ও তার পরের version প্রয়োজন। Node 23 supported range-এর বাইরে। অন্য কিছু করার আগে node -v চালান। কারণ unsupported runtime-এর startup failure-কে broken install মনে হতে পারে, ফলে runtime-এর পরিবর্তে মানুষ package পুনরায় install করতে শুরু করে।