Configurar o dsh: chaves, modelos e endpoints
Veja onde o dsh guarda a configuração no Linux, como usar uma chave DeepSeek ou um endpoint Ollama local e o que sai da máquina em cada modo.
Onde o dsh mantém a configuração
O dsh (DeepSeek Harness) mantém os dados do harness em $DSH_HOME, que por padrão é ~/.dsh, e lê a configuração partilhada dos agentes a partir de uma raiz separada, $DSH_AGENTS_HOME, que por padrão é ~/.agents. Tudo o que definir na Web UI é escrito aí como ficheiros de texto simples. Ao mover a configuração para outro servidor, copie o diretório inicial do harness e quaisquer instruções e skills globais a partir da raiz partilhada dos agentes.
Quatro caminhos contêm as principais definições do harness, os segredos e os logs das sessões.
~/.dsh/profiles/<profile>/cordis.patch.ymlcontém as definições que a Web UI escreve para esse perfil, incluindo as rotas do provider e do modelo.dsh webexecuta o perfilweb, pelo que o ficheiro é~/.dsh/profiles/web/cordis.patch.yml.~/.dsh/.credentials.yamlcontém os segredos. As definições guardam apenas uma referência a uma credencial, pelo que o valor da chave fica num único ficheiro.~/.dsh/profiles/contém os perfis nomeados, e~/.dsh/sessions/contém os logs de sessões guardados.~/.dsh/cordis.patch.ymlé a sua própria camada de patches. É aplicada sobre a configuração incorporada para todos os perfis e tem precedência sobre o ficheiro do perfil. Por isso, uma edição da Web UI que esta camada substituiria é recusada em vez de ser guardada.
A raiz partilhada dos agentes fica fora de $DSH_HOME porque outras ferramentas de agentes também a utilizam. O dsh lê as instruções globais do utilizador a partir de ~/.agents/AGENTS.md e procura skills em ~/.agents/skills/. Defina DSH_AGENTS_HOME para mover essa raiz.
As versões anteriores mantinham estas definições em ~/.dsh/settings.yaml. As versões atuais importam esse ficheiro uma vez para o perfil ativo e mudam-lhe o nome para settings.yaml.imported. Por isso, um guia antigo que indique a edição de settings.yaml aponta agora para um ficheiro que o dsh já não lê.
A DeepSeek distribui o harness como uma pré-visualização para developers licenciada ao abrigo da MIT, e o README indica que haverá alterações incompatíveis. Os nomes dos campos e os caminhos deste guia correspondem à documentação atual do repositório, verificada em 5 November 2026. Compare-os com a documentação da versão instalada antes de copiar a configuração de qualquer guia, incluindo este, porque uma pré-visualização pode mudar nomes entre versões.
O mínimo honesto até à primeira saída
dsh requer Node.js 24.9 ou posterior. Em 5 de novembro de 2026, o seu package.json declara >=24.9.0, portanto a linha 22 não é suportada. Node 24.0 a 24.8 também não é suficiente. Verifique primeiro a versão, porque uma incompatibilidade de versões faz o arranque falhar e o erro parece indicar um package danificado.
node -v
npx @deepseek-ai/dsh webnpx descarrega o package do registo npm e inicia a Web UI em http://127.0.0.1:3080. Faz bind ao endereço de loopback, o que significa que a porta não é acessível a partir de outra máquina, mesmo quando a firewall permite o acesso. Num VPS, encaminhe-a através de SSH em vez de abrir a porta 3080 à Internet. Se esse URL apresentado for a parte confusa, por que dsh arranca nesse endereço explica o que o bind de loopback protege e o que não protege.
ssh -N -L 3080:127.0.0.1:3080 you@your-serverAbra http://127.0.0.1:3080 no seu portátil e, em seguida, aceda a Settings e Models. O cartão DeepSeek tem um campo para a chave de API. Cole a chave de platform.deepseek.com e guarde-a. A rota do modelo fica utilizável imediatamente, sem reinício, porque o servidor em execução armazena a credencial e resolve a referência em tempo real. Aceder à Web UI do dsh num servidor remoto explica o caso do túnel e do reverse proxy, e instalar o DeepSeek Harness num VPS explica a preparação do servidor assumida por este guia.
Depois de guardar, verifique o que a aplicação criou.
ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yamlDeverá ver .credentials.yaml e profiles/, com as definições da Web UI em profiles/web/cordis.patch.yml. Um diretório home criado por uma build mais antiga também pode conter settings.yaml.imported. Se stat apresentar um modo diferente de 600, execute chmod 600 ~/.dsh/.credentials.yaml. Um ficheiro de credenciais legível pelo grupo expõe a sua chave às contas desse grupo; um ficheiro legível por todos expõe-a a todas as outras contas do sistema.
Para a primeira execução sem browser, basta um comando.
npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"O perfil headless executa uma única sessão e apresenta a resposta final.
Variáveis de ambiente ou o ficheiro de configuração
dsh pode resolver uma chave a partir de credenciais guardadas ou de alternativas de ambiente.
Um fornecedor de catálogo (DeepSeek, Anthropic, OpenAI e os restantes fornecedores integrados) aceita uma chave através da página Models ou utiliza a alternativa de ambiente suportada quando nenhuma credencial guardada a fornece. O valor é colocado em ~/.dsh/.credentials.yaml, e as suas definições guardam apenas uma referência para esse valor. A Web UI nunca volta a mostrar a chave depois de esta ser guardada.
Um fornecedor personalizado pode indicar uma referência de credencial com apiKeyEnv, que também suporta alternativas de ambiente. Este é o formato apresentado pela documentação para uma entrada num patch de perfil, como ~/.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]Adicione primeiro um fornecedor através da Web UI. Em seguida, abra cordis.patch.yml do perfil e copie a estrutura que foi gravada. Durante uma pré-visualização para programadores, o aninhamento é a parte com maior probabilidade de mudar. O ficheiro que a aplicação acabou de gravar está sempre atualizado.
apiKeyEnv é resolvido através do arquivo de credenciais: o ficheiro guardado tem prioridade, seguido do ambiente de arranque, de .env do diretório a partir do qual o comando foi executado e, depois, de $DSH_HOME/.env. Uma chave exportada apenas numa sessão interativa não fica visível para uma unidade systemd. Sem outra fonte de credenciais, a mesma configuração que funciona quando introduz dsh web manualmente devolve MISSING_CREDENTIAL quando é executada como serviço. Dê à unidade o seu próprio ficheiro.
[Service]
EnvironmentFile=/etc/dsh/dsh.envMantenha esse ficheiro com o modo 600 e atribua-o ao utilizador com que o serviço é executado.
Escolher modelos e o ID que não pode ser renomeado
Todos os provedores configurados aparecem no seletor de modelos. Selecionar um modelo também o define como padrão para novas sessões. As sessões que já enviaram um pedido mantêm o modelo registado nelas, por isso a alteração não reescreve uma conversa antiga.
O ID do provedor é permanente. Os pedidos, as sessões guardadas, os modelos padrão e as referências às credenciais apontam todos para esse ID, por isso não existe um botão para o renomear. Alterá-lo significa criar um novo provedor e eliminar o antigo. Escolha um nome que possa manter: local-ollama em vez de test2.
Os modelos personalizados sem capacidade de imagem herdada aceitam apenas texto, salvo indicação em contrário. Adicione input: [text, image] a uma entrada de modelo para declarar suporte para imagens ou defina defaultInput ao nível da rota como fallback para modelos que o catálogo não descreva. Na própria rota da DeepSeek, um modelo sem modalidades declaradas é considerado apenas de texto. Por isso, selecione uma entrada do catálogo com suporte para imagens (deepseek-flash por padrão) antes de anexar uma imagem. Uma imagem enviada para um modelo que não declara suporte para imagens é recusada antes de qualquer envio.
Aponte o dsh para um endpoint local para manter o código no servidor
Ollama disponibiliza uma API compatível com OpenAI em http://127.0.0.1:11434/v1. O dsh comunica com qualquer URL base compatível com OpenAI através de um provider personalizado, por isso os dois ligam-se diretamente. Configure primeiro o servidor de modelos: alojar um LLM com Ollama num VPS explica a instalação e a transferência do modelo.
Confirme que o endpoint responde antes de configurar o dsh.
ollama list
curl -s http://127.0.0.1:11434/v1/modelsollama list mostra a tag exata de cada modelo transferido. Copie essa string. curl devolve os mesmos modelos em JSON. Uma lista vazia significa que o Ollama está em execução, mas não tem modelos transferidos. Connection refused significa que o Ollama não está em execução ou não está a escutar na porta 11434.
Escolha um modelo que seja executado nesta máquina. Um servidor Ollama com sessão iniciada também disponibiliza modelos na cloud através do mesmo endereço local. Uma tag de cloud, como gemma4:cloud, é executada nos servidores do Ollama. Assim, os seus prompts saem do servidor, embora o dsh comunique apenas com 127.0.0.1.
Adicione agora o provider ao patch do perfil. Forneça um valor de chave API não vazio nesta configuração. O servidor Ollama local ignora esse valor.
- 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>Exporte a variável no ambiente em que o processo do dsh a possa ver.
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.envTrês falhas abrangem quase todas as tentativas de configuração. MISSING_CREDENTIAL significa que a referência indicada por apiKeyEnv não foi resolvida para nenhum valor. Verifique as credenciais guardadas e o ambiente de arranque, não apenas o seu terminal. UNKNOWN_MODEL significa que id não corresponde a um modelo configurado. Compare-o com ollama list carácter a carácter, incluindo a tag depois dos dois pontos. Um erro 401 ao obter os modelos disponíveis vem da descoberta de modelos, que chama GET /models no URL base. Os endpoints que não disponibilizam esse caminho precisam que os modelos sejam introduzidos manualmente.
Existe mais um problema comum com o URL base. Não inclua /v1 no final. Caso contrário, os pedidos chegam a caminhos que o Ollama não disponibiliza, a chamada devolve 404 e o modelo nunca é executado. O sufixo faz parte da superfície compatível com OpenAI. Não é apenas decoração.
Se o Ollama for executado noutra máquina, o endereço dessa máquina passa a ser o URL base. Os seus prompts atravessam então a rede em texto simples através de HTTP sem TLS. Mantenha o serviço no mesmo host ou coloque-o atrás de TLS (transport layer security) e autenticação: proteger um endpoint Ollama exposto.
O que sai da máquina em cada modo
Com uma chave do DeepSeek e o endpoint padrão, as solicitações ao modelo vão para a API do DeepSeek. Essa solicitação inclui o seu prompt, o conteúdo dos ficheiros que o agente leu para responder, a saída dos comandos executados e quaisquer resultados de ferramentas que decidiu incluir. O seu código-fonte fica dentro desse payload sempre que o agente abre um ficheiro. É assim que funciona um modelo alojado, e por isso é importante considerar em que diretório inicia o agente.
As versões atuais também anexan, por padrão, um sufixo ainda não aceite do log de eventos da sessão às solicitações através do adaptador nativo do DeepSeek, incluindo gateways configurados, num campo dsh_session_log separado. O modelo nunca o vê, mas o destino da solicitação recebe-o. Desative esta opção em Settings, General ("Upload Session Log when using the official model API") ou defina enabled: false no plugin session-log-deepseek. As opções de telemetria abaixo não controlam este envio.
Os perfis fornecidos também enviam os nomes e as versões dos pacotes de plugins ativos através do adaptador nativo do DeepSeek, num campo dsh_plugin_packages separado. Defina enabled: false em plugin-package-inventory-deepseek para impedir esse envio.
Com outro fornecedor do catálogo ou com um gateway da empresa, o mesmo payload vai para esse fornecedor. O URL base indica exatamente o destino.
Com um endpoint local, a solicitação ao modelo vai para 127.0.0.1:11434, mas o endereço de loopback, por si só, não a mantém na máquina. A documentação do Ollama diz: "To use cloud models through this server, sign in to Ollama,". Portanto, um modelo na cloud selecionado através desse mesmo servidor local envia os seus prompts e o seu código para a cloud do Ollama. A solicitação ao modelo só permanece na máquina quando o próprio modelo é executado localmente. Mesmo nesse caso, três tipos de dados continuam a atravessar a rede. npx descarrega o pacote do registry do npm. Qualquer ferramenta executada pelo agente pode aceder à Internet por conta própria, incluindo os servidores MCP (model context protocol) aos quais se ligou. Executar servidores MCP numa VPS explica este caso em detalhe. Um plugin pertence à mesma categoria, porque instalá-lo executa código de outro autor com as permissões do seu agente. Por isso, é importante verificar a que recursos um plugin pode aceder antes de o instalar. A telemetria também atravessa a rede: as versões atuais autorizam a exportação para o DeepSeek sempre que envia feedback, tanto com um modelo local como com um modelo alojado.
Por padrão, a telemetria está limitada ao feedback. DSH_TELEMETRY_MODE seleciona o modo e, na configuração base fornecida atualmente, um valor não definido ou vazio resolve para FEEDBACK_ONLY. Nesse modo, a atividade normal não autoriza a captura de telemetria. Quando envia feedback escrito, cria ou edita uma avaliação, edita uma nota ou retira feedback, o dsh autoriza a exportação para https://dsh-otel-collector.deepseeksvc.com/v1/logs do prefixo do log da sessão que ainda não foi entregue ao exportador, através desse evento de feedback e incluindo o contexto herdado. A entrega completa não é garantida: um evento demasiado grande é rejeitado sem truncamento, e prefixos grandes podem permanecer parcialmente por enviar quando a CLI termina. Os lotes autorizados podem continuar a ser enviados sem outra interação ou chamada ao modelo. O README da telemetria diz que isto se aplica "for all users and providers", portanto executar o modelo localmente não desativa a telemetria. DISABLED não cria qualquer transporte OpenTelemetry (OTel). FULL já não é aceite: qualquer valor diferente dos dois valores permitidos é rejeitado com unsupported mode. Uma exportação de feedback pode incluir texto de mensagens, argumentos e resultados de ferramentas e caminhos do workspace. Trate o feedback como uma autorização para enviar esse prefixo da sessão ao DeepSeek.
Para uma desativação imediata que não dependa de definir corretamente a cadeia do modo, defina DSH_TELEMETRY_DISABLED=1. Qualquer valor não vazio é uma exclusão autorizada, incluindo 0 e false. A variável é lida antes do início da execução, portanto o código do projeto não pode reativá-la durante a sessão. O endereço padrão do coletor é dsh-otel-collector.deepseeksvc.com; DSH_TELEMETRY_OTLP_URL substitui-o.
Verifique a configuração em vez de confiar nela. Com uma tarefa em execução, liste as ligações de saída mantidas pelo processo.
sudo ss -tnp | grep -i nodeCom um modelo executado localmente, o tráfego do modelo usa a porta de loopback 11434, mas as ligações públicas ainda podem ser originadas por ferramentas sem que qualquer feedback seja enviado. Os perfis fornecidos incluem pesquisa e obtenção de conteúdo na Web, e a predefinição de permissões não restringe o acesso à rede. Identifique cada destino público antes de o atribuir à telemetria. A ocorrência temporal, por si só, não prova que uma ligação seja a exportação de feedback. Esta captura também pode não detetar ligações de curta duração. Esta verificação abrange apenas o processo dsh: o tráfego de um modelo na cloud sai do servidor Ollama, portanto confirme também que o modelo id não é identificado como um modelo na cloud. Identifique qualquer outro destino antes de continuar. O que um agente de programação envia para fora executa a mesma verificação noutros harnesses e explica como interpretar o resultado.
Onde os segredos não devem ser armazenados
- Histórico do shell.
export DEEPSEEK_API_KEY=sk-...é gravado em~/.bash_historyem texto simples e permanece lá muito depois de a chave ser renovada. Prefixe o comando com um espaço quandoHISTCONTROL=ignorespaceestiver definido ou ignore o shell e grave o valor diretamente num ficheiro com modo 600. - Ficheiros dot versionados. Uma chave em
~/.bashrcou~/.zshrcfica a umagit addde distância de um repositório público se mantiver ficheiros dot no git. Executegit grep -I -n 'sk-'nesse repositório antes de fazer push. - Ficheiros de patch do perfil. Use
apiKeyEnvpara fornecedores personalizados, para quecordis.patch.ymlcontenha um nome de variável em vez de um segredo. Os ficheiros de configuração são frequentemente colados em relatórios de problemas e conversas com o suporte. Os ficheiros de credenciais não. - Saída de
enve capturas de ecrã do terminal. Tudo o que imprimir o ambiente completo também imprime a chave. - Cópias de segurança. Vale a pena fazer cópia de segurança de
~/.dsh, mas.credentials.yamlno seu interior é um segredo ativo. Exclua esse ficheiro ou encripte o arquivo.
Estas regras não são específicas do dsh, e manter os segredos fora dos ficheiros env do Compose aborda o mesmo problema no lado dos contentores do mesmo servidor.
Trabalhar com uma versão de pré-visualização
Fixe a versão que testou, porque uma versão de pré-visualização pode alterar uma chave de configuração numa versão de correção e fazer com que o seu provider deixe de carregar. Se a instalação com a versão fixada recusar iniciar, ou se npx continuar a fornecer uma build que não pediu, os erros de instalação e de versão produzidos por uma pré-visualização explicam a cache do npx e a versão do npm incluída no Node. Mantenha o diretório inicial cordis.patch.yml e os ficheiros de patch em profiles/ sob controlo de versões, excluindo o ficheiro de credenciais, para conseguir ver o que mudou depois de uma atualização.
Duas flags ajudam quando um perfil não se comporta como esperado. --dump-default-config mostra a configuração predefinida composta sem iniciar o serviço, e --dump-config mostra a configuração composta do seu perfil da mesma forma. Comparar as duas mostra o que a sua camada de patch alterou efetivamente, o que é mais rápido do que ler as camadas manualmente.
dsh --profile web --dump-configQuando algo falhar depois de uma atualização, execute primeiro esse comando. Uma chave que mudou entre versões aparece como um ramo em falta no dump, e a correção consiste numa alteração de uma linha, não numa reinstalação.
FAQ
Onde o dsh armazena a minha chave da API DeepSeek?
Em $DSH_HOME/.credentials.yaml, que é ~/.dsh/.credentials.yaml, a menos que defina DSH_HOME manualmente. A página Models grava a chave nesse ficheiro, e as suas definições contêm apenas uma referência a ela. Assim, o segredo fica num único ficheiro. Verifique o modo com stat -c '%a %n' ~/.dsh/.credentials.yaml e defina-o como 600 se for menos restritivo. Um provider personalizado pode evitar completamente o ficheiro ao indicar uma variável de ambiente com apiKeyEnv.
Como faço o dsh utilizar um modelo local em vez da API DeepSeek?
Adicione um provider personalizado cujo URL base seja o seu endpoint local compatível com OpenAI. No Ollama, esse URL é http://127.0.0.1:11434/v1, com api: openai-completions e um modelo id copiado exatamente de ollama list. Forneça um valor de chave da API não vazio para esta configuração; o servidor Ollama ignora-o. Confirme que o endpoint responde com curl -s http://127.0.0.1:11434/v1/models antes de editar qualquer configuração do dsh, porque um endpoint indisponível e uma configuração incorreta produzem erros semelhantes.
O dsh envia o meu código para algum lugar por predefinição?
Com um modelo alojado, sim. O seu prompt e o conteúdo dos ficheiros lidos pelo agente fazem parte do pedido à API desse fornecedor. Os pedidos através do adaptador nativo do DeepSeek, incluindo gateways configurados, também transportam um sufixo do registo da sessão por predefinição, até desativar esse carregamento em Settings, General. Com um modelo executado localmente pelo Ollama, o pedido vai para o loopback e permanece na máquina. No entanto, um modelo na cloud, como gemma4:cloud, encaminha-o para a cloud do Ollama através do mesmo endereço de loopback. A pesquisa e a obtenção de conteúdo na Web integradas, outras ferramentas e plugins podem contactar serviços públicos de forma independente do feedback. A telemetria é um fluxo separado: nas releases atuais, DSH_TELEMETRY_MODE resolve para FEEDBACK_ONLY quando não está definida. Assim, o feedback autoriza a exportação do prefixo do registo da sessão através desse evento, incluindo o contexto herdado, para todos os providers, incluindo modelos locais. A entrega não é garantida, e os carregamentos autorizados podem continuar depois da interação de feedback. Defina DISABLED para não utilizar nenhum exporter ou defina DSH_TELEMETRY_DISABLED=1 para uma exclusão voluntária lida antes do início da execução.
Por que razão o dsh indica MISSING_CREDENTIAL quando a minha variável está definida?
Porque a referência indicada por apiKeyEnv tem de ser resolvida pelas fontes de credenciais do dsh. As credenciais guardadas têm prioridade sobre o ambiente de execução. Depois vêm .env e $DSH_HOME/.env do diretório a partir do qual o processo foi iniciado. Uma variável exportada na sua shell não chega a um serviço systemd, à sessão de outro utilizador nem a um processo iniciado antes de a variável ser exportada. Coloque o valor num EnvironmentFile com modo 600 para a unidade ou exporte-o na mesma shell que inicia o dsh. Confirme o que o processo em execução realmente contém com sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.
De que versão do Node.js o dsh precisa?
Do Node.js 24.9 ou posterior, de acordo com o package.json do repositório em 5 November 2026. A linha 22 já não é suportada, e o Node 24.0 a 24.8 também não é suficiente. Execute node -v antes de qualquer outra coisa, porque uma falha de arranque causada por um runtime não suportado parece uma instalação avariada e leva as pessoas a reinstalar o pacote em vez do runtime.