Como configurar o dsh: chaves, modelos e endpoints

Onde o dsh guarda a configuração

O dsh (DeepSeek Harness) guarda a configuração num único diretório: $DSH_HOME, cujo valor predefinido é ~/.dsh. Tudo o que definir na Web UI é gravado nesse diretório como ficheiros de texto simples. Copie esse diretório para outro servidor e o novo sistema comporta-se como o anterior.

Quatro caminhos contêm tudo o que irá alterar.

• ~/.dsh/settings.yaml contém as definições escritas manualmente e pela UI, incluindo as rotas do fornecedor e dos modelos.
• ~/.dsh/.credentials.yaml conté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/storages/ contém as sessões guardadas.
• ~/.dsh/cordis.patch.yml é a sua própria camada de alterações. Ela é aplicada sobre a configuração integrada para cada perfil.

A DeepSeek anunciou o harness como uma versão de pré-visualização para programadores, licenciada sob a licença MIT, em 17 August 2026, e o README indica que haverá alterações incompatíveis. Os nomes dos campos e os caminhos neste guia correspondem à documentação do repositório em August 2026. Confirme-os na documentação da versão instalada antes de copiar a configuração de qualquer guia, incluindo este, porque uma versão de pré-visualização pode alterar os nomes entre releases.

O mínimo honesto para obter a primeira resposta

dsh precisa do Node.js 22.19 ou posterior na linha 22, ou do Node 24 ou superior. O Node 23 fica fora desse intervalo. Verifique primeiro a versão, porque uma incompatibilidade de versão faz o arranque falhar e o erro parece indicar um pacote danificado.

node -v
npx @deepseek-ai/dsh web

npx transfere o pacote do registo npm e inicia a Web UI em http://127.0.0.1:3080. Liga-se ao endereço de loopback, o que significa que a porta não fica acessível a partir de outra máquina, mesmo quando a firewall permite o acesso. Num VPS, encaminhe a ligação através de SSH em vez de abrir a porta 3080 para a Internet. Se esse URL apresentado for a parte confusa, porque o dsh inicia nesse endereço explica o que a ligação ao loopback protege e o que não protege.

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

Abra http://127.0.0.1:3080 no seu portátil e aceda a Settings e Models. O cartão DeepSeek tem um campo para a chave da API. Cole a chave obtida em 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 aborda o túnel e o caso do reverse proxy, enquanto instalar o DeepSeek Harness num VPS aborda 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.yaml

Deverá ver settings.yaml, .credentials.yaml e profiles/. Se stat apresentar um modo diferente de 600, execute chmod 600 ~/.dsh/.credentials.yaml. Um ficheiro de credenciais legível pelo grupo ou por todos os utilizadores entrega a sua chave a todas as outras contas do servidor.

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 ficheiro de configuração

Existem duas formas de fornecer uma chave ao dsh, e não são intercambiáveis.

Um fornecedor do catálogo (DeepSeek, Anthropic, OpenAI e os restantes da lista integrada) recebe a chave através da página Models. O valor é colocado em ~/.dsh/.credentials.yaml, e as suas definições guardam apenas uma referência a ele. A Web UI nunca volta a mostrar a chave depois de a guardar.

Um fornecedor personalizado pode indicar, em alternativa, uma variável de ambiente através de apiKeyEnv. Este é o formato apresentado pela documentação para ~/.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]

Adicione primeiro um fornecedor através da Web UI. Em seguida, abra ~/.dsh/settings.yaml e copie a estrutura que o programa escreveu. Durante uma pré-visualização para programadores, a estrutura de aninhamento é a parte com maior probabilidade de mudar. O ficheiro que a aplicação acabou de escrever está sempre atualizado.

apiKeyEnv é lido a partir do ambiente do processo dsh, não da sua shell de login. Uma chave exportada numa sessão interativa fica invisível para uma unidade systemd. Por isso, a mesma configuração que funciona quando executa dsh web manualmente devolve MISSING_CREDENTIAL através de um serviço. Forneça à unidade o seu próprio ficheiro.

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

Mantenha esse ficheiro com o modo 600 e atribua-lhe como proprietário o utilizador com que o serviço é executado.

Escolher modelos e o ID que não pode renomear

Todos os providers configurados aparecem no seletor de modelos. Selecionar um modelo também faz dele o modelo predefinido para novas sessões. As sessões que já existem mantêm o modelo registado nelas, por isso a alteração não modifica uma conversa antiga.

O Provider ID é permanente. Os pedidos, as sessões guardadas, os modelos predefinidos e as referências a credenciais apontam todos para esse ID, por isso não existe um botão para o renomear. Alterá-lo significa criar um novo provider e eliminar o antigo. Escolha um nome que possa manter: local-ollama em vez de test2.

Os modelos são apenas de texto, salvo indicação em contrário. Adicione input: [text, image] a uma entrada de modelo para declarar suporte a imagens ou defina defaultInput ao nível da rota como fallback para modelos que o catálogo não descreva. A rota de chat-completions do próprio DeepSeek aceita apenas texto e não pode ser configurada de outra forma, por isso uma imagem anexada a essa rota é recusada antes de qualquer envio.

Aponte o dsh para um endpoint local para manter o código no servidor

O 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 provedor personalizado, por isso os dois ligam-se diretamente. Configure primeiro o servidor de modelos: alojar um LLM com Ollama numa VPS explica a instalação e o download do modelo.

Confirme que o endpoint responde antes de configurar o dsh.

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

ollama list mostra a tag exata de cada modelo que descarregou. Copie essa string. curl devolve os mesmos modelos em JSON. Uma lista vazia significa que o Ollama está a funcionar sem nenhum modelo descarregado. Connection refused significa que o Ollama não está a funcionar ou não está a escutar na porta 11434.

Agora adicione o provedor. O Ollama exige um campo de chave de API e ignora o respetivo valor, por isso qualquer string não vazia funciona.

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>

Exporte a variável no ambiente em que o processo do dsh a consiga 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.env

Três falhas abrangem quase todas as tentativas. MISSING_CREDENTIAL significa que o dsh não conseguiu ler a variável indicada por apiKeyEnv, por isso verifique o ambiente do processo, não o ambiente do seu terminal. UNKNOWN_MODEL significa que id não corresponde a nenhum modelo configurado, por isso 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 na sua URL base; os endpoints que não disponibilizam esse caminho exigem que introduza os modelos manualmente.

Existe ainda uma armadilha relacionada com a URL base. Não inclua /v1 nela. Caso contrário, os pedidos chegam a caminhos que o Ollama não disponibiliza, a chamada devolve um erro 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 estiver a funcionar noutra máquina, o endereço dessa máquina passa a ser a URL base. Os prompts atravessam então a rede em texto simples através de HTTP simples. Mantenha-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 da DeepSeek, cada pedido vai para a API da DeepSeek. Esse pedido inclui o seu prompt, o conteúdo dos ficheiros que o agente leu para responder, a saída dos comandos que executou e quaisquer resultados de ferramentas que tenha escolhido incluir. O seu código-fonte está nesse payload sempre que o agente abriu um ficheiro. É assim que funciona um modelo alojado, e é por isso que deve considerar a partir de que diretório inicia o agente.

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, o pedido ao modelo vai para 127.0.0.1:11434 e permanece na máquina. Nenhuma parte do seu código chega a um fornecedor de modelos. Ainda há três elementos que atravessam a rede. npx descarrega o pacote do registo npm. Qualquer ferramenta executada pelo agente pode aceder à Internet por conta própria, incluindo servidores MCP (model context protocol) que tenha ligado; 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, vale a pena verificar a que um plugin pode aceder antes de o instalar. E há a telemetria, se a ativar.

A telemetria fica desativada até dar consentimento. DSH_TELEMETRY_MODE é a opção de consentimento, e valores não definidos, vazios ou não reconhecidos são resolvidos para DISABLED. Nesse estado, dsh não cria nenhum fornecedor, processador ou exportador OpenTelemetry (OTel), pelo que um perfil novo não faz qualquer pedido de telemetria pela rede. FEEDBACK_ONLY ativa a partilha de logs de sessão acionada por feedback. FULL também permite o envio de relatórios pelo launcher. O feed da sessão pode exportar conteúdo da sessão, dados de ferramentas, prompts e caminhos do workspace. Por isso, considere que FULL envia o seu trabalho para a DeepSeek.

Para uma desativação completa que não dependa de obter corretamente a cadeia do modo, defina DSH_TELEMETRY_DISABLED=1. Qualquer valor não vazio é uma opção de não participação autoritativa. A variável é lida antes do início da execução, pelo que o código do projeto não a pode voltar a ativar durante a sessão. O endereço predefinido do collector é harness-telemetry.deepseeksvc.com. É útil conhecer este nome ao consultar os seus próprios logs de firewall.

Verifique em vez de confiar na configuração. Com uma tarefa em execução, liste as ligações de saída mantidas pelo processo.

sudo ss -tnp | grep -i node

No modo de modelo local, deverá ver a ligação de loopback para a porta 11434 e nenhuma ligação para um endereço público. Vale a pena identificar qualquer outra ligação 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 guardados

• Histórico do shell. export DEEPSEEK_API_KEY=sk-... é escrito em ~/.bash_history em texto simples e permanece aí muito depois de a chave ser substituída. Prefixe o comando com um espaço quando HISTCONTROL=ignorespace estiver definido ou ignore o shell e escreva o valor diretamente num ficheiro com modo 600.
• Ficheiros dot versionados. Uma chave em ~/.bashrc ou ~/.zshrc fica a uma git add de distância de um repositório público se mantiver os ficheiros dot no git. Execute git grep -I -n 'sk-' nesse repositório antes de fazer push.
• settings.yaml. Use apiKeyEnv para fornecedores personalizados, para que o ficheiro contenha 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 env e capturas de ecrã do terminal. Tudo o que imprimir o ambiente completo imprimirá também a chave.
• Cópias de segurança. Vale a pena fazer cópia de segurança de ~/.dsh, mas .credentials.yaml dentro dele é 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é-lançamento

Fixe a versão que testou, porque uma versão de pré-lançamento pode alterar uma chave de configuração numa versão de correção e o seu provider deixa de carregar. Se a instalação com a versão fixada se recusar a arrancar, ou se npx continuar a fornecer uma build que não pediu, os erros de instalação e de versão produzidos por uma versão de pré-lançamento explicam a cache do npx e o npm incluído no seu Node. Mantenha settings.yaml e cordis.patch.yml no controlo de versões, excluindo o ficheiro de credenciais, para poder ver o que mudou depois de uma atualização.

Duas flags ajudam quando um perfil não se comporta como esperado. --dump-default-config apresenta a configuração predefinida composta sem iniciar o serviço, e --dump-config apresenta a configuração composta do seu perfil da mesma forma. Comparar as duas mostra o que a sua camada de alterações realmente modificou. Isto é mais rápido do que ler as camadas manualmente.

dsh --profile web --dump-config

Quando 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. A correção consiste numa edição de uma linha, e não numa reinstalação.

FAQ

Onde o dsh armazena a minha chave de API do 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 local, e as suas definições contêm apenas uma referência a ela, pelo que o segredo fica num único ficheiro. Verifique o modo com stat -c '%a %n' ~/.dsh/.credentials.yaml e defina-o como 600 se estiver menos restritivo. Um fornecedor personalizado pode evitar completamente o ficheiro, indicando uma variável de ambiente com apiKeyEnv.

Como faço o dsh usar um modelo local em vez da API do DeepSeek?

Adicione um fornecedor personalizado cujo URL base seja o seu endpoint local compatível com OpenAI. No caso do Ollama, é http://127.0.0.1:11434/v1, com api: openai-completions e um modelo id copiado exatamente de ollama list. O Ollama exige um valor para a chave de API, mas ignora-o, pelo que qualquer string não vazia funciona. 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 local por predefinição?

Com um modelo alojado, sim. O seu prompt e o conteúdo dos ficheiros lidos pelo agente estão incluídos no pedido da API enviado para esse fornecedor. Com um endpoint local, esse pedido vai para o loopback e permanece na máquina. A telemetria é um fluxo separado e está desativada por predefinição: DSH_TELEMETRY_MODE resolve para DISABLED quando não está definida e, nesse estado, não é criado nenhum exporter. Defina DSH_TELEMETRY_DISABLED=1 para optar por não participar; essa opção é lida antes do início da execução.

Por que motivo o dsh comunica MISSING_CREDENTIAL quando a minha variável está definida?

Porque o dsh lê a variável indicada por apiKeyEnv a partir do ambiente do seu próprio processo. Uma variável exportada na sua shell não chega a um serviço systemd, à sessão de outro utilizador ou 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 contém efetivamente com sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.

De que versão do Node.js precisa o dsh?

Do Node.js 22.19 ou posterior na linha 22, ou da versão 24 ou posterior. O Node 23 fica fora do intervalo suportado. Execute node -v antes de qualquer outra ação, porque uma falha de arranque causada por um runtime não suportado parece uma instalação danificada e leva os utilizadores a reinstalar o pacote em vez do runtime.