dsh configureren: API keys en modellen instellen

Waar dsh zijn configuratie bewaart

dsh (DeepSeek Harness) bewaart zijn configuratie in één map: $DSH_HOME, die standaard ~/.dsh is. Alles wat u in de Web UI instelt, wordt daar als platte tekstbestanden opgeslagen. Kopieer die map naar een andere server en de nieuwe machine gedraagt zich als de oude.

Vier paden bevatten alles waar u mee zult werken.

• ~/.dsh/settings.yaml bevat handmatig en via de UI geschreven instellingen, inclusief uw provider- en modelroutes.
• ~/.dsh/.credentials.yaml bevat de geheimen. Instellingen bevatten alleen een verwijzing naar een inloggegeven, dus de sleutelwaarde zelf staat in één bestand.
• ~/.dsh/profiles/ bevat benoemde profielen en ~/.dsh/storages/ bevat opgeslagen sessies.
• ~/.dsh/cordis.patch.yml is uw eigen patch-laag. Deze wordt voor elk profiel over de ingebouwde configuratie heen toegepast.

DeepSeek kondigde de harness op 17 augustus 2026 aan als een MIT-gelicentieerde developer preview, en de README vermeldt dat er wijzigingen zullen komen die de compatibiliteit verbreken. De veldnamen en paden in deze handleiding komen overeen met de documentatie in de repository van augustus 2026. Controleer deze tegen de documentatie van de versie die u heeft geïnstalleerd voordat u configuraties uit een handleiding kopieert, inclusief deze, omdat een preview namen tussen releases kan wijzigen.

Het absolute minimum voor de eerste output

dsh vereist Node.js 22.19 of hoger op de 22-lijn, of 24 en hoger. Node 23 valt buiten dat bereik. Controleer eerst de versie, omdat een versie-mismatch bij het opstarten faalt en de foutmelding lijkt op een defect pakket.

node -v
npx @deepseek-ai/dsh web

npx downloadt het pakket uit de npm-registry en start de Web UI op http://127.0.0.1:3080. Het bindt aan het loopback-adres, wat betekent dat de poort niet bereikbaar is vanaf een andere machine, zelfs niet als uw firewall dit toestaat. Forward deze op een VPS via SSH in plaats van poort 3080 open te stellen voor het internet. Als de getoonde URL onduidelijk is, legt waarom dsh op dat adres start uit wat de loopback-binding beschermt en wat niet.

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

Open http://127.0.0.1:3080 op uw laptop en ga naar Settings en Models. De DeepSeek-kaart bevat één veld voor een API-key. Plak de key van platform.deepseek.com en sla deze op. De model-route wordt direct bruikbaar, zonder herstart, omdat de draaiende server de inloggegevens opslaat en de referentie live verwerkt. De dsh Web UI bereiken op een externe server behandelt de tunnel en het scenario met een reverse proxy, en DeepSeek Harness installeren op een VPS behandelt de voorbereiding van de server waar deze handleiding vanuit gaat.

Kijk na het opslaan wat de applicatie heeft aangemaakt.

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

U zou settings.yaml, .credentials.yaml en profiles/ moeten zien. Als stat een andere modus dan 600 weergeeft, voer dan chmod 600 ~/.dsh/.credentials.yaml uit. Een bestand met inloggegevens dat leesbaar is voor de groep of voor iedereen, stelt uw key bloot aan elk ander account op de server.

Voor een eerste run zonder browser is één commando voldoende.

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

Het headless-profiel voert één sessie uit en print het uiteindelijke antwoord.

Omgevingsvariabelen of het configuratiebestand

Er zijn twee manieren om een sleutel aan dsh te verstrekken, en deze zijn niet uitwisselbaar.

Een catalogusprovider (DeepSeek, Anthropic, OpenAI en de rest van de ingebouwde lijst) ontvangt de sleutel via de pagina Models. De waarde wordt ingevoerd in ~/.dsh/.credentials.yaml en uw instellingen bevatten enkel een verwijzing ernaar. De Web UI toont de sleutel nooit meer nadat u deze heeft opgeslagen.

Een aangepaste provider kan in plaats daarvan een omgevingsvariabele benoemen met apiKeyEnv. Dit is de structuur die de documentatie voor ~/.dsh/settings.yaml voorschrijft.

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]

Voeg eerst één provider toe via de Web UI, open daarna ~/.dsh/settings.yaml en kopieer de structuur die daar is geschreven. Tijdens een developer preview is de nesting het onderdeel dat het meest waarschijnlijk verandert, en het bestand dat de applicatie zojuist heeft geschreven is altijd actueel.

apiKeyEnv wordt gelezen vanuit de omgeving van het dsh-proces, niet vanuit uw login-shell. Een sleutel die in een interactieve sessie is geëxporteerd, is onzichtbaar voor een systemd-unit. Daarom geeft dezelfde configuratie die werkt wanneer u handmatig dsh web typt, de foutmelding MISSING_CREDENTIAL wanneer deze als service draait. Voorzie de unit van een eigen bestand.

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

Houd dat bestand op mode 600, met de gebruiker waaronder de service draait als eigenaar.

Modellen kiezen en de ID die u niet kunt hernoemen

Elke geconfigureerde provider verschijnt in de modelkiezer. Het selecteren van een model maakt dit ook de standaard voor nieuwe sessies. Bestaande sessies behouden het model dat erin is vastgelegd, dus overschakelen herschrijft een oude conversatie niet.

De Provider ID is permanent. Verzoeken, opgeslagen sessies, modelstandaarden en referentieverwijzingen wijzen er allemaal naar, dus er is geen knop voor hernoemen. Deze wijzigen betekent een nieuwe provider aanmaken en de oude verwijderen. Kies een naam waar u mee kunt leven: local-ollama in plaats van test2.

Modellen zijn alleen tekst, tenzij u anders aangeeft. Voeg input: [text, image] toe aan een modelvermelding om ondersteuning voor afbeeldingen te declareren, of stel defaultInput in op routeniveau als fallback voor modellen die niet in de catalogus worden beschreven. De eigen chat-completions-route van DeepSeek is alleen tekst en kan niet anders worden geconfigureerd, dus een afbeelding die aan die route wordt toegevoegd, wordt geweigerd voordat er iets wordt verzonden.

Wijs dsh naar een lokaal eindpunt zodat uw code op de server blijft

Ollama biedt een OpenAI-compatibele API op http://127.0.0.1:11434/v1. dsh communiceert met elke OpenAI-compatibele base URL via een aangepaste provider, waardoor de twee direct met elkaar verbonden zijn. Configureer eerst de modelserver: het zelf hosten van een LLM met Ollama op een VPS behandelt de installatie en het ophalen van het model.

Controleer of het eindpunt reageert voordat u dsh configureert.

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

ollama list toont de exacte tag van elk model dat u heeft opgehaald. Kopieer die tekenreeks. curl geeft dezelfde modellen terug als JSON. Een lege lijst betekent dat Ollama draait zonder dat er modellen zijn opgehaald. Connection refused betekent dat Ollama niet draait of niet luistert op poort 11434.

Voeg nu de provider toe. Ollama vereist een API-sleutelveld en negeert de waarde ervan, dus elke niet-lege tekenreeks volstaat.

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>

Exporteer de variabele zodat het dsh-proces deze kan inzien.

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

Drie fouten komen bij bijna elke poging voor. MISSING_CREDENTIAL betekent dat dsh de variabele met de naam apiKeyEnv niet kon lezen; controleer dus de omgeving van het proces, niet de omgeving van uw terminal. UNKNOWN_MODEL betekent dat de id niet overeenkomt met een geconfigureerd model; vergelijk deze daarom teken voor teken met ollama list, inclusief de tag na de dubbele punt. Een 401-fout bij het ophalen van beschikbare modellen komt voort uit modeldetectie, die GET /models aanroept op uw base URL; eindpunten die dit pad niet ondersteunen, vereisen dat modellen handmatig worden ingevoerd.

Een ander veelvoorkomend probleem is de base URL. Laat /v1 weg en de verzoeken komen terecht op paden die Ollama niet ondersteunt, waardoor de aanroep terugkomt als een 404 en het model nooit wordt uitgevoerd. Het achtervoegsel is onderdeel van de OpenAI-compatibele interface, niet slechts decoratie.

Als Ollama op een andere machine draait, wordt het adres van die machine de base URL en worden uw prompts in leesbare tekst via onversleuteld HTTP over het netwerk verstuurd. Houd het op dezelfde host of plaats het achter TLS (transport layer security) en authenticatie: het beveiligen van een blootgesteld Ollama-eindpunt.

Wat verlaat de machine in elke modus

Bij gebruik van een DeepSeek-sleutel gaat elk verzoek naar de API van DeepSeek. Dat verzoek bevat uw prompt, de inhoud van de bestanden die de agent heeft gelezen om deze te beantwoorden, de output van de uitgevoerde commando's en alle resultaten van tools die de agent heeft gebruikt. Uw broncode bevindt zich in die payload zodra de agent een bestand opent. Zo werkt een gehost model, en dit is de reden om na te denken in welke map u de agent start.

Bij een andere catalogusprovider of een bedrijfs-gateway gaat dezelfde payload naar die leverancier. De base URL vertelt u precies waarheen.

Bij een lokaal eindpunt gaat het modelverzoek naar 127.0.0.1:11434 en blijft het op de machine. Geen enkel deel van uw code bereikt een modelleverancier. Drie zaken gaan echter nog steeds over het netwerk. npx downloadt het pakket van het npm-register. Elke tool die de agent uitvoert, kan zelfstandig het internet bereiken, inclusief MCP-servers (model context protocol) waarmee u verbinding heeft gemaakt, wat in MCP-servers draaien op een VPS in detail wordt behandeld. Een plugin valt in diezelfde categorie, omdat het installeren ervan de code van een andere auteur uitvoert met de rechten van uw agent; het is daarom de moeite waard om te controleren wat een plugin kan bereiken voordat u deze installeert. En telemetrie, als u dit inschakelt.

Telemetrie staat uit totdat u zich hiervoor aanmeldt. DSH_TELEMETRY_MODE is de schakelaar voor toestemming, en niet-ingestelde, lege of niet-herkende waarden resulteren in DISABLED. In die staat bouwt dsh geen OpenTelemetry (OTel) provider, processor of exporter op, waardoor een nieuw profiel helemaal geen telemetrie-netwerkverzoek doet. FEEDBACK_ONLY schakelt het delen van sessielogs op basis van feedback in. FULL staat ook rapportage door de launcher toe. De sessiefeed kan sessie-inhoud, tooldata, prompts en werkruimtepaden exporteren, dus beschouw FULL als het versturen van uw werk naar DeepSeek.

Voor een harde stop die niet afhankelijk is van het correct instellen van de modus-string, stelt u DSH_TELEMETRY_DISABLED=1 in. Elke niet-lege waarde is een definitieve opt-out en wordt gelezen voordat de run start, zodat projectcode dit niet halverwege een sessie kan terugdraaien. Het standaard collector-adres is harness-telemetry.deepseeksvc.com, wat een nuttige naam is om te kennen wanneer u uw eigen firewall-logs leest.

Controleer de instelling in plaats van deze te vertrouwen. Terwijl een taak draait, kunt u de uitgaande verbindingen van het proces opvragen.

sudo ss -tnp | grep -i node

In de lokale-modelmodus hoort u alleen de loopback-verbinding naar 11434 te zien en geen verbinding met een publiek adres. Alles wat daarvan afwijkt, is het onderzoeken waard voordat u doorgaat. Wat een coding agent naar huis stuurt voert dezelfde controle uit bij andere omgevingen en legt uit hoe u het resultaat moet lezen.

Waar geheimen niet thuishoren

• Shell-geschiedenis. export DEEPSEEK_API_KEY=sk-... wordt in leesbare tekst naar ~/.bash_history geschreven en blijft daar lang nadat u de sleutel heeft geroteerd. Laat het commando voorafgaan door een spatie wanneer HISTCONTROL=ignorespace is ingesteld, of sla de shell over en schrijf de waarde direct naar een bestand met modus 600.
• Gecommitteerde dotfiles. Een sleutel in ~/.bashrc of ~/.zshrc is slechts één git add verwijderd van een openbare repository als u dotfiles in git beheert. Voer git grep -I -n 'sk-' uit in die repository voordat u een push uitvoert.
• settings.yaml. Gebruik apiKeyEnv voor aangepaste providers, zodat het bestand een variabelenaam bevat in plaats van een geheim. Configuratiebestanden worden vaak in bugrapporten en supportchats geplakt. Referentiebestanden met inloggegevens horen daar niet in thuis.
• Uitvoer van env en terminal-screenshots. Alles wat de volledige omgeving afdrukt, drukt ook de sleutel af.
• Back-ups. ~/.dsh is het waard om te back-uppen, maar .credentials.yaml daarbinnen is een actief geheim. Sluit dat bestand uit of versleutel het archief.

Deze regels zijn niet specifiek voor dsh, en het buiten Compose env-bestanden houden van geheimen behandelt hetzelfde probleem aan de containerzijde van dezelfde server.

Werken met een developer preview

Zet de versie die u heeft getest vast, omdat een preview in een patch-release een configuratiesleutel kan wijzigen, waardoor uw provider niet meer laadt. Als de vastgezette installatie vervolgens weigert te starten, of als npx u blijft voorzien van een build waar u niet om heeft gevraagd, behandelt de installatie- en versie-fouten die een preview veroorzaakt de npx-cache en de npm die bij uw Node-installatie wordt geleverd. Houd settings.yaml en cordis.patch.yml in versiebeheer, met het bestand met inloggegevens uitgesloten, zodat u kunt zien wat er na een upgrade is gewijzigd.

Twee vlaggen helpen wanneer een profiel zich niet gedraagt zoals verwacht. --dump-default-config toont de samengestelde standaardconfiguratie zonder op te starten, en --dump-config toont op dezelfde wijze de samengestelde configuratie voor uw profiel. Door beide te vergelijken ziet u wat uw patch-laag daadwerkelijk heeft gewijzigd; dit is sneller dan het handmatig uitlezen van de lagen.

dsh --profile web --dump-config

Wanneer er na een upgrade iets defect raakt, voer dit dan als eerste uit. Een sleutel die tussen releases is verplaatst, verschijnt als een ontbrekende tak in de dump, en de oplossing is een aanpassing van één regel in plaats van een herinstallatie.

FAQ

Waar slaat dsh mijn DeepSeek API-sleutel op?

In $DSH_HOME/.credentials.yaml, wat ~/.dsh/.credentials.yaml is tenzij u zelf DSH_HOME instelt. De pagina Models schrijft de sleutel daar weg en uw instellingen bevatten enkel een verwijzing ernaar, zodat het geheim in één bestand staat. Controleer de rechten met stat -c '%a %n' ~/.dsh/.credentials.yaml en stel deze in op 600 als ze ruimer zijn. Een aangepaste provider kan het bestand volledig vermijden door een omgevingsvariabele te benoemen met apiKeyEnv.

Hoe laat ik dsh een lokaal model gebruiken in plaats van de DeepSeek API?

Voeg een aangepaste provider toe waarvan de base URL uw lokale OpenAI-compatibele endpoint is. Voor Ollama is dat http://127.0.0.1:11434/v1, met api: openai-completions en een model id dat exact is gekopieerd uit ollama list. Ollama vereist een API-sleutelwaarde maar negeert deze, dus elke niet-lege string volstaat. Bevestig dat het endpoint antwoordt met curl -s http://127.0.0.1:11434/v1/models voordat u een dsh-configuratie bewerkt, omdat een onbereikbaar endpoint en een onjuiste configuratie vergelijkbare fouten opleveren.

Verstuurt dsh standaard mijn code naar een externe locatie?

Bij een gehost model wel. Uw prompt en de inhoud van de bestanden die de agent heeft gelezen, zitten in het API-verzoek aan die leverancier. Bij een lokaal endpoint gaat dat verzoek naar loopback en blijft het op de machine. Telemetrie is een aparte stroom en staat standaard uit: DSH_TELEMETRY_MODE resulteert in DISABLED wanneer deze niet is ingesteld, en in die staat wordt er geen exporter aangemaakt. Stel DSH_TELEMETRY_DISABLED=1 in voor een opt-out die wordt uitgelezen voordat de uitvoering start.

Waarom rapporteert dsh MISSING_CREDENTIAL terwijl mijn variabele is ingesteld?

Omdat dsh de variabele die wordt benoemd door apiKeyEnv leest vanuit zijn eigen procesomgeving. Een variabele die in uw shell is geëxporteerd, bereikt geen systemd-service, de sessie van een andere gebruiker of een proces dat is gestart voordat u de variabele exporteerde. Plaats de waarde in een EnvironmentFile met rechten 600 voor de unit, of exporteer deze in dezelfde shell die dsh start. Controleer wat het draaiende proces daadwerkelijk bevat met sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.

Welke Node.js-versie heeft dsh nodig?

Node.js 22.19 of later in de 22-reeks, of 24 en hoger. Node 23 valt buiten het ondersteunde bereik. Voer node -v uit voordat u iets anders doet, omdat een opstartfout door een niet-ondersteunde runtime eruitziet als een defecte installatie en gebruikers aanzet tot het opnieuw installeren van het pakket in plaats van de runtime.