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 verwijst naar ~/.dsh. Alles wat u instelt in de Web UI wordt daar opgeslagen als tekstbestanden. Kopieer deze map naar een andere server en de nieuwe machine gedraagt zich identiek aan de oude.

Vier paden bevatten alles waar u mee zult werken.

• ~/.dsh/settings.yaml bevat handmatig en via de UI ingevoerde instellingen, inclusief uw provider- en modelroutes.
• ~/.dsh/.credentials.yaml bevat de geheimen. Instellingen bevatten slechts een verwijzing naar een inloggegeven, waardoor de sleutelwaarde zelf in één bestand staat.
• ~/.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 toegepast boven op de ingebouwde configuratie.

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 van 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 tussen releases namen kan wijzigen.

Het absolute minimum om als eerste uit te voeren

dsh vereist Node.js 22.19 of nieuwer binnen de 22-reeks, of versie 24 en hoger. Node 23 valt buiten dit bereik. Controleer eerst de versie, omdat een versieconflict 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. Op een VPS kunt u dit beter via SSH doorsturen in plaats van poort 3080 open te stellen voor het internet.

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-sleutel. Plak de sleutel van platform.deepseek.com en sla deze op. De modelroute 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 hoort settings.yaml, .credentials.yaml en profiles/ te 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 sleutel bloot aan elk ander account op de server.

Voor een eerste uitvoering 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 voorschrijft voor ~/.dsh/settings.yaml.

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 is geëxporteerd in een interactieve sessie is onzichtbaar voor een systemd-unit. Daarom geeft dezelfde configuratie die werkt wanneer u handmatig dsh web typt, een MISSING_CREDENTIAL-foutmelding onder een service. 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. Reeds bestaande sessies behouden het model dat erin is vastgelegd, dus wisselen overschrijft een oude conversatie niet.

De Provider ID is permanent. Verzoeken, opgeslagen sessies, modelstandaarden en verwijzingen naar inloggegevens wijzen hier 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 aan 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: zelf een LLM hosten 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 deze string. curl geeft dezelfde modellen terug als JSON. Een lege lijst betekent dat Ollama draait, maar dat er geen 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-key-veld en negeert de waarde ervan, dus elke niet-lege string 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 foutmeldingen dekken bijna elke mislukte poging. MISSING_CREDENTIAL betekent dat dsh de variabele met de naam apiKeyEnv niet kon lezen; controleer daarom 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 karakter voor karakter met ollama list, inclusief de tag na de dubbele punt. Een 401-fout bij het ophalen van beschikbare modellen komt voort uit model-discovery, 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 resulteert in een 404 en het model niet 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 via het netwerk verzonden in leesbare tekst over onversleuteld HTTP. Houd de service op dezelfde host, of beveilig deze met TLS (transport layer security) en authenticatie: een blootgesteld Ollama-eindpunt beveiligen.

Wat verlaat de machine in elke modus

Met een DeepSeek-key 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 tool-resultaten die de agent heeft toegevoegd. Uw broncode bevindt zich in die payload telkens wanneer de agent een bestand opent. Zo werkt een gehost model, en daarom is het belangrijk 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 geeft precies aan waarheen.

Bij een lokaal endpoint 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 nog steeds over het netwerk. npx downloadt het pakket van de npm-registry. Elke tool die de agent uitvoert, kan zelfstandig het internet bereiken, inclusief MCP-servers (model context protocol) waarmee u verbinding heeft gemaakt, wat in running MCP servers on a VPS in detail wordt behandeld. En telemetrie, als u dit inschakelt.

Telemetrie staat uit totdat u zich 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, dus een nieuw profiel verstuurt helemaal geen telemetrie-netwerkverzoeken. 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, tool-data, prompts en werkmap-paden 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 deze 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 weergeven.

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 verdergaat. What a coding agent sends home 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. Plaats een spatie voor het commando 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 voor inloggegevens horen daar niet bij.
• 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, en .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. 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 veranderd.

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 doorlezen van de lagen.

dsh --profile web --dump-config

Wanneer er na een upgrade iets defect raakt, voert u dit 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 standaard ~/.dsh/.credentials.yaml is, tenzij u DSH_HOME zelf instelt. De pagina Models schrijft de sleutel daarheen en uw instellingen bevatten enkel een verwijzing, 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 op te geven 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 tekenreeks 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 veroorzaken.

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, bevinden zich 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 gelezen 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 modus 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, waardoor gebruikers het pakket opnieuw installeren in plaats van de runtime.