dsh configureren: API keys en endpoints instellen
Ontdek waar dsh configuratiebestanden opslaat op Linux. Leer hoe u DeepSeek API keys en lokale Ollama endpoints koppelt en zie precies welke data uw systeem verlaat.
Waar dsh zijn configuratie bewaart
dsh (DeepSeek Harness) bewaart zijn harness-data onder $DSH_HOME, wat standaard ~/.dsh is, en leest gedeelde agent-configuratie vanuit een aparte root, $DSH_AGENTS_HOME, wat standaard ~/.agents is. Alles wat u in de Web UI instelt, wordt daar als platte tekstbestanden opgeslagen. Kopieer de harness-home en alle globale instructies en skills vanuit de gedeelde agent-root wanneer u uw configuratie naar een andere server verplaatst.
Vier paden bevatten de belangrijkste harness-instellingen, secrets en sessielogs.
~/.dsh/profiles/<profile>/cordis.patch.ymlbevat de instellingen die de Web UI voor dat profiel schrijft, inclusief uw provider- en modelroutes.dsh webdraait hetweb-profiel, dus het bestand is~/.dsh/profiles/web/cordis.patch.yml.~/.dsh/.credentials.yamlbevat de secrets. Instellingen bevatten alleen een verwijzing naar een credential, dus de sleutelwaarde zelf staat in één bestand.~/.dsh/profiles/bevat benoemde profielen en~/.dsh/sessions/bevat opgeslagen sessielogs.~/.dsh/cordis.patch.ymlis uw eigen patch-laag. Deze wordt toegepast over de ingebouwde configuratie voor elk profiel en heeft voorrang op het profielbestand. Een wijziging in de Web UI die door deze laag zou worden overschreven, wordt daarom geweigerd in plaats van opgeslagen.
De gedeelde agent-root blijft buiten $DSH_HOME omdat andere agent-tools deze delen. dsh leest gebruikersspecifieke globale instructies vanuit ~/.agents/AGENTS.md en scant ~/.agents/skills/ op skills; stel DSH_AGENTS_HOME in om die root te verplaatsen.
Eerdere builds bewaarden deze instellingen in ~/.dsh/settings.yaml. Huidige builds importeren dat bestand eenmalig in het actieve profiel en hernoemen het naar settings.yaml.imported. Een oudere handleiding die u adviseert om settings.yaml te bewerken, verwijst dus naar een bestand dat dsh niet langer leest.
DeepSeek publiceert de harness als een MIT-gelicentieerde developer preview en de README vermeldt dat er wijzigingen zullen zijn die de compatibiliteit verbreken. De veldnamen en paden in deze handleiding komen overeen met de huidige repository-documentatie, gecontroleerd op 5 november 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 wijzigt tussen releases.
Het absolute minimum voor de eerste uitvoering
dsh vereist Node.js 24.9 of nieuwer. Sinds 5 november 2026 specificeert het package.json-bestand >=24.9.0, waardoor de 22-reeks niet wordt ondersteund. Node 24.0 tot en met 24.8 is eveneens ontoereikend. Controleer eerst de versie, aangezien een versieconflict bij het opstarten faalt en de foutmelding doet vermoeden dat het pakket beschadigd is.
node -v
npx @deepseek-ai/dsh webnpx 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. Als de getoonde URL onduidelijk is, legt waarom dsh op dat adres start uit wat de loopback-binding beveiligt en wat niet.
ssh -N -L 3080:127.0.0.1:3080 you@your-serverOpen 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 de reverse proxy-situatie, en DeepSeek Harness installeren op een VPS behandelt de voorbereiding van de server waar deze handleiding vanuit gaat.
Controleer na het opslaan wat de applicatie heeft aangemaakt.
ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yamlU hoort .credentials.yaml en profiles/ te zien, met de instellingen van de Web UI in profiles/web/cordis.patch.yml. Een homedirectory die door een oudere build is aangemaakt, kan ook settings.yaml.imported bevatten. Als stat een andere modus dan 600 weergeeft, voer dan chmod 600 ~/.dsh/.credentials.yaml uit. Een voor de groep leesbaar bestand met inloggegevens stelt uw sleutel bloot aan accounts in die groep; een voor iedereen leesbaar bestand stelt deze bloot aan elk ander account op de machine.
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 toont het uiteindelijke antwoord.
Omgevingsvariabelen of het configuratiebestand
dsh kan een sleutel ophalen uit opgeslagen referenties of uit omgevingsvariabelen als terugvaloptie.
Een catalogusprovider (DeepSeek, Anthropic, OpenAI en de rest van de ingebouwde lijst) accepteert een sleutel via de pagina Models of gebruikt de ondersteunde omgevingsvariabele als terugvaloptie wanneer geen opgeslagen referentie de sleutel levert. De waarde komt in ~/.dsh/.credentials.yaml te staan. In uw instellingen staat alleen een verwijzing ernaar. De Web UI toont de sleutel niet opnieuw nadat u deze hebt opgeslagen.
Een aangepaste provider kan met apiKeyEnv een verwijzing naar een referentie benoemen. Ook hiervoor zijn omgevingsvariabelen als terugvaloptie beschikbaar. Dit is de structuur die de documentatie geeft voor een item in een profielpatch, zoals ~/.dsh/profiles/web/cordis.patch.yml.
- id: llm-pi-ai
config:
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 cordis.patch.yml van het profiel en kopieer de structuur die daar is geschreven. Tijdens een preview voor ontwikkelaars is de nesting het onderdeel dat waarschijnlijk het vaakst verandert. Het bestand dat de applicatie zojuist heeft geschreven, is altijd actueel.
apiKeyEnv wordt opgelost via de referentieopslag: het opgeslagen bestand heeft voorrang, gevolgd door de omgevingsvariabelen bij het starten, .env van de aanroepende map en daarna $DSH_HOME/.env. Een sleutel die alleen in een interactieve sessie is geëxporteerd, is niet beschikbaar voor een systemd-unit. Zonder een andere bron voor referenties geeft dezelfde configuratie die werkt wanneer u dsh web handmatig invoert, onder een service MISSING_CREDENTIAL terug. Geef de unit een eigen bestand.
[Service]
EnvironmentFile=/etc/dsh/dsh.envGeef dat bestand modus 600 en maak de gebruiker waaronder de service draait eigenaar ervan.
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. Sessies waarvoor al een verzoek is verzonden, behouden het model dat daarin is vastgelegd; wisselen herschrijft dus geen oude conversatie.
De Provider ID is permanent. Verzoeken, opgeslagen sessies, modelstandaarden en referenties naar inloggegevens verwijzen 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.
Aangepaste modellen zonder overgeërfde afbeeldingsmogelijkheden zijn alleen tekst, tenzij u anders aangeeft. Voeg input: [text, image] toe aan een modelinvoer om afbeeldingsondersteuning te declareren, of stel defaultInput in op routeniveau als fallback voor modellen die niet in de catalogus worden beschreven. Op de eigen route van DeepSeek telt een model zonder gedeclareerde modaliteiten als alleen-tekst, dus kies een catalogusinvoer die afbeeldingen ondersteunt (standaard deepseek-flash) voordat u een afbeelding bijvoegt. Een afbeelding die wordt verzonden naar een model dat geen afbeeldingsondersteuning declareert, wordt geweigerd voordat er iets wordt verzonden.
dsh naar een lokaal eindpunt laten verwijzen, zodat uw code op de server blijft
Ollama biedt een OpenAI-compatibele API op http://127.0.0.1:11434/v1. dsh kan via een aangepaste provider met elke OpenAI-compatibele basis-URL communiceren. Daardoor kunnen beide direct met elkaar verbinden. Stel de modelserver eerst in: een LLM zelf hosten met Ollama op een VPS behandelt de installatie en het ophalen van het model.
Controleer of het eindpunt antwoord geeft voordat u dsh configureert.
ollama list
curl -s http://127.0.0.1:11434/v1/modelsollama list toont de exacte tag van elk model dat u hebt opgehaald. Kopieer deze tekenreeks. curl retourneert dezelfde modellen als JSON. Een lege lijst betekent dat Ollama actief is, maar dat er geen modellen zijn opgehaald. Connection refused betekent dat Ollama niet actief is of niet op 11434 luistert.
Kies een model dat op deze machine kan draaien. Een bij Ollama aangemelde server biedt via hetzelfde lokale adres ook cloudmodellen aan. Een cloudtag zoals gemma4:cloud draait op de servers van Ollama. Uw prompts verlaten de server dus, ook al communiceert dsh uitsluitend met 127.0.0.1.
Voeg de provider nu toe aan de profielpatch. Geef voor deze configuratie een niet-lege waarde op voor de API-sleutel. De lokale Ollama-server negeert deze waarde.
- id: llm-pi-ai
config:
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 op een plaats waar het dsh-proces deze kan zien.
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.envDrie fouten dekken vrijwel elke poging met deze configuratie. MISSING_CREDENTIAL betekent dat de verwijzing waarnaar apiKeyEnv verwijst niets opleverde. Controleer daarom de opgeslagen referenties en de omgeving waarin het proces wordt gestart, niet alleen uw terminal. UNKNOWN_MODEL betekent dat id niet overeenkomt met een geconfigureerd model. Vergelijk deze waarde teken voor teken met ollama list, inclusief de tag na de dubbele punt. Een 401-fout bij het ophalen van beschikbare modellen ontstaat tijdens modeldetectie. Daarbij wordt GET /models op uw basis-URL aangeroepen. Eindpunten die dit pad niet aanbieden, vereisen dat u de modellen handmatig opgeeft.
De basis-URL vormt nog een mogelijk probleem. Laat /v1 niet weg. Anders komen de verzoeken terecht op paden die Ollama niet aanbiedt. De aanroep resulteert dan in een 404-fout en het model wordt niet uitgevoerd. Dit achtervoegsel maakt deel uit van het OpenAI-compatibele oppervlak en is niet alleen opmaak.
Als Ollama op een andere machine draait, wordt het adres van die machine de basis-URL. Uw prompts gaan dan via het netwerk in leesbare tekst over plain HTTP. Houd Ollama op dezelfde host of plaats het achter TLS (transport layer security) en authenticatie: een blootgesteld Ollama-eindpunt beveiligen.
Wat verlaat de machine in elke modus
Bij gebruik van een DeepSeek-key en het standaard-endpoint gaan modelverzoeken 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 uitvoer van de uitgevoerde commando's en alle toolresultaten die de agent heeft toegevoegd. Uw broncode bevindt zich in die payload zodra de agent een bestand heeft geopend. Zo werkt een gehost model, en dit is de reden om na te denken in welke map u de agent start.
Huidige releases voegen standaard ook een niet-geaccepteerd achtervoegsel van het eventlogboek van de sessie toe aan verzoeken via de native DeepSeek-adapter, inclusief geconfigureerde gateways, als een afzonderlijk dsh_session_log-veld. Het model ziet dit nooit, maar de bestemming van het verzoek ontvangt het wel. Schakel dit uit in Settings, General ("Upload Session Log when using the official model API"), of stel enabled: false in op de session-log-deepseek-plugin. De onderstaande telemetrie-schakelaars controleren deze upload niet.
Meegeleverde profielen sturen ook actieve plugin-pakketnamen en versies via de native DeepSeek-adapter in een afzonderlijk dsh_plugin_packages-veld. Stel enabled: false in op plugin-package-inventory-deepseek om die bijdrage te stoppen.
Bij een andere catalogusprovider of een bedrijfs-gateway gaat dezelfde payload in plaats daarvan naar die leverancier. De base URL geeft precies aan waarheen.
Bij een lokaal endpoint gaat het modelverzoek naar 127.0.0.1:11434, maar het loopback-adres alleen houdt het niet op de machine. De documentatie van Ollama stelt: "To use cloud models through this server, sign in to Ollama," dus een cloudmodel dat via diezelfde lokale server is geselecteerd, stuurt uw prompts en code naar de cloud van Ollama. Alleen wanneer het model zelf lokaal draait, blijft het modelverzoek op de machine. Drie zaken verlaten zelfs dan 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 hebt gemaakt, wat running MCP servers on a VPS in detail behandelt. 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 checking what a plugin can reach before you install it. En telemetrie, die huidige releases toestaan voor export naar DeepSeek wanneer u feedback indient, bij een lokaal model precies zoals bij een gehost model.
Telemetrie is standaard beperkt tot feedback. DSH_TELEMETRY_MODE selecteert de modus, en in de huidige meegeleverde basisconfiguratie resulteert een niet-ingestelde of lege waarde in FEEDBACK_ONLY. In die modus staat normale activiteit geen telemetrie-opname toe. Wanneer u schriftelijke feedback indient, een beoordeling aanmaakt of bewerkt, een notitie bewerkt of feedback intrekt, staat dsh export toe van het sessielog-voorvoegsel dat nog niet aan de exporteur is overhandigd, via dat feedback-event en inclusief overgeërfde context, naar https://dsh-otel-collector.deepseeksvc.com/v1/logs. Volledige aflevering is niet gegarandeerd: een te groot event wordt geweigerd zonder afkapping, en grote voorvoegsels kunnen gedeeltelijk onverzonden blijven bij het afsluiten van de CLI. Geautoriseerde batches kunnen blijven verzenden zonder verdere interactie of modelaanroep. De telemetrie-README stelt dat dit geldt "for all users and providers", dus het lokaal draaien van het model schakelt dit niet uit. DISABLED bouwt helemaal geen OpenTelemetry (OTel)-transport op. FULL wordt niet langer geaccepteerd: elke andere waarde dan die twee wordt geweigerd met unsupported mode. Een feedback-export kan berichttekst, tool-argumenten en resultaten, en werkmap-paden bevatten, dus beschouw feedback als een autorisatie om dat sessie-voorvoegsel naar DeepSeek te sturen.
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 autoritaire opt-out, inclusief 0 en false, en deze wordt gelezen voordat de run start, zodat projectcode dit niet halverwege de sessie kan terugdraaien. Het standaard collector-adres is dsh-otel-collector.deepseeksvc.com; DSH_TELEMETRY_OTLP_URL overschrijft dit.
Verifieer in plaats van de instelling te vertrouwen. Terwijl een taak draait, kunt u de uitgaande verbindingen van het proces weergeven.
sudo ss -tnp | grep -i nodeBij een lokaal uitgevoerd model gebruikt modelverkeer loopback-poort 11434, maar openbare verbindingen kunnen nog steeds afkomstig zijn van tools zonder dat er feedback is ingediend. De meegeleverde profielen bevatten web search en fetch, en de standaard permissie-preset beperkt netwerktoegang niet. Identificeer elke openbare bestemming voordat u deze toeschrijft aan telemetrie; timing alleen stelt niet vast dat een verbinding de feedback-export is. Deze snapshot kan ook kortstondige verbindingen missen. Deze controle dekt alleen het dsh-proces: het verkeer van een cloudmodel verlaat de Ollama-server, dus bevestig dat het model id ook geen cloud-tag is. Al het overige is het waard om te identificeren voordat u doorgaat. What a coding agent sends home voert dezelfde controle uit tegen andere harnesses en legt uit hoe het resultaat moet worden gelezen.
Waar geheimen niet thuishoren
- Shell-geschiedenis.
export DEEPSEEK_API_KEY=sk-...wordt in leesbare tekst naar~/.bash_historygeschreven en blijft daar lang nadat u de sleutel heeft geroteerd. Plaats een spatie voor het commando wanneerHISTCONTROL=ignorespaceis ingesteld, of sla de shell over en schrijf de waarde direct naar een bestand met modus 600. - Gecommitteerde dotfiles. Een sleutel in
~/.bashrcof~/.zshrcis slechts ééngit addverwijderd van een openbare repository als u dotfiles in git beheert. Voergit grep -I -n 'sk-'uit in die repository voordat u een push uitvoert. - Profiel-patchbestanden. Gebruik
apiKeyEnvvoor aangepaste providers, zodatcordis.patch.ymleen variabelenaam bevat in plaats van een geheim. Configuratiebestanden worden vaak in bugrapporten en ondersteuningschats geplakt. Referentiebestanden met inloggegevens horen daar niet bij. - Uitvoer van
enven terminal-screenshots. Alles wat de volledige omgeving afdrukt, drukt ook de sleutel af. - Back-ups.
~/.dshis het waard om te back-uppen, maar.credentials.yamldaarbinnen 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 wordt geleverd. Houd de home cordis.patch.yml en de patchbestanden onder profiles/ in versiebeheer, waarbij het bestand met inloggegevens is 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 lezen van de lagen.
dsh --profile web --dump-configWanneer er na een upgrade iets kapot gaat, voert u dat 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 Modellen schrijft de sleutel daarheen 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 basis-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. Geef een niet-lege API-sleutelwaarde op voor deze configuratie; de lokale Ollama-server negeert deze. Bevestig dat het endpoint antwoordt met curl -s http://127.0.0.1:11434/v1/models voordat u een dsh-configuratie bewerkt, omdat een niet-bereikbaar 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, bevinden zich in het API-verzoek aan die leverancier. Verzoeken via de native DeepSeek-adapter, inclusief geconfigureerde gateways, bevatten standaard ook een sessielog-achtervoegsel totdat u die upload uitschakelt in Instellingen, Algemeen. Bij een model dat Ollama lokaal draait, gaat dat verzoek naar loopback en blijft het op de machine, maar een cloudmodel zoals gemma4:cloud stuurt het door naar de cloud van Ollama via hetzelfde loopback-adres. Ingebouwde webzoekopdrachten en fetch-functies, andere tools en plug-ins kunnen onafhankelijk van feedback contact opnemen met openbare diensten. Telemetrie is een afzonderlijke stroom: in huidige releases wordt DSH_TELEMETRY_MODE omgezet naar FEEDBACK_ONLY wanneer deze niet is ingesteld, dus feedback autoriseert de export van het sessielog-voorvoegsel via die gebeurtenis, inclusief overgeërfde context, voor elke provider, lokale modellen inbegrepen. Aflevering is niet gegarandeerd en geautoriseerde uploads kunnen doorgaan na de feedback-interactie. Stel dit in op DISABLED voor geen exporteur, of 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 de verwijzing die wordt benoemd door apiKeyEnv moet worden opgelost in de inloggegevensbronnen van dsh. Opgeslagen inloggegevens krijgen voorrang op de opstartomgeving, gevolgd door .env en $DSH_HOME/.env van de aanroepende map. 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 deze 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 24.9 of nieuwer, volgens de package.json van de repository per 5 november 2026. De 22-lijn wordt niet langer ondersteund en Node 24.0 tot 24.8 is eveneens onvoldoende. 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.