Como instalar o DeepSeek Harness (dsh): aplicativo para desktop, comando de uma linha com npx, compilação a partir do código-fonte e plugins

DeepSeek Harness (dsh) — o runtime de agente de código aberto que a DeepSeek lançou em 13 de agosto de 2026 — ganhou um cliente desktop oficial em 24 de setembro de 2026. É um aplicativo empacotado para Windows e macOS em Apple silicon, publicado pelo próprio host de download da DeepSeek com o runtime do harness embutido: sem instalação do Node.js, sem npx, sem terminal. A linha de comando não desapareceu — npx @deepseek-ai/dsh web ainda é a rota mais rápida no Linux, que a versão desktop não cobre. Duas coisas para saber antes de começar: dsh não é um modelo — é a camada de harness que conecta um modelo como DeepSeek V4 Flash 0731 ou DeepSeek V4 Pro 0813 a ferramentas, arquivos e um terminal — e todos os seus canais ainda são uma prévia para desenvolvedores, então espere mudanças que quebram compatibilidade entre versões. Este guia aborda o aplicativo desktop, o one-liner npx, a compilação a partir do código-fonte, o modo headless, plugins, MCP e as arestas ásperas honestas.

O que é o DeepSeek Harness — e o que ele não é

A fórmula interna da Deep​Seek, confirmada pelo pesquisador sênior Chen Deli, é Modelo + Harness = Agente. O modelo é o cérebro; o harness é tudo o que o transforma em algo que realiza trabalho: gerenciamento de contexto e memória, chamada de ferramentas, planejamento de tarefas, leitura e escrita de arquivos, execução de terminal, feedback de erros e a decisão de quando uma tarefa está concluída. O Deep​Seek Harness é essa camada, com código aberto sob a licença MIT em 13 de agosto de 2026 — no mesmo dia em que a versão DeepSeek V4 Pro 0813 foi disponibilizada na API da Deep​Seek.

Dois fatos definem a experiência de instalação. Primeiro, a arquitetura é "tudo é um plugin", construída sobre o Cordis, um contêiner de plugins TypeScript — então o que você instala é um núcleo pequeno mais um conjunto de plugins que fornecem adaptadores de modelo, ferramentas, sessões e UI. Segundo, os canais npm hoje são 0.1.5-rc.3 no latest e 0.1.7-rc.2 no next, ambos candidatos a release que o próprio projeto sinaliza como prévia de desenvolvedor: o README avisa, em letras maiúsculas, que mudanças que quebram a compatibilidade estão chegando. A popularidade é real — 50.000 estrelas no GitHub nas primeiras 12 horas e 235.000 no final de setembro de 2026 — mas estrelas medem interesse, não estabilidade. Planeje sua instalação como planeja uma prévia: rápida de testar, barata de descartar.

Antes de começar: os requisitos reais do sistema.

Para as instalações por linha de comando, o único requisito obrigatório é Node.js. O projeto tem como alvo o intervalo de engines ^22.19.0 || >=24.0.0 — em termos simples, Node 22 ou, ou qualquer Node 24.x. Verifique a sua com node --version. Se você estiver usando uma versão mais antiga do Node, a instalação via n falhará ou se comportará mal, em vez de degradar graciosamente. O aplicativo para desktop abaixo inclui seu próprio runtime, portanto não precisa de Node.js de forma alguma.

Tudo o mais é mais leve do que o pessoal model-first supõe:

• Uma chave de API do modelo. dsh executa um modelo real; ele precisa de uma chave para a API da Deep​Seek ou de qualquer provedor compatível com Open​AI que você configurar. Você pode adicionar uma na interface web após a primeira inicialização.

• pnpm — apenas para a compilação a partir do código-fonte. Instale uma vez com npm install -g pnpm.

• ~1 GB de disco livre para o pacote npm, o workspace e os logs de sessão, além do que um modelo local precisaria (o próprio dsh não executa pesos). O instalador para desktop é mais pesado — 288 MB para o .exe do Windows, uma imagem de disco de 368 MB no macOS — porque carrega esse runtime internamente.

• SO: a rota npm funciona no Windows, macOS e Linux. O aplicativo de desktop é mais restrito — apenas Windows x64 e macOS com Apple silicon, sem build para Mac Intel e sem alvo Linux. O SDK Python é ainda mais restrito (Linux x64/arm64, macOS 14+ arm64 — sem Windows nativo), abordado abaixo.

Você não precisa de uma GPU. O harness apenas orquestra; o modelo é executado remotamente por meio de uma API.

Método 1 — o aplicativo oficial para desktop (Windows e macOS)

Em 24 de setembro de 2026, a DeepSeek publicou a primeira build de desktop empacotada do DeepSeek Harness. É uma camada Electron em torno da mesma Web UI, com o runtime dsh incluído, portanto não há nada para instalar primeiro nem nada para iniciar manualmente: sem Node.js, sem npx, sem terminal e sem aba do navegador aberta em 127.0.0.1:3080. O código-fonte está no repositório público em apps/desktop como o pacote @deepseek-ai/dsh-desktop, os artefatos são servidos a partir do host de download de produção da própria DeepSeek em download.deepseek.com/dsh-desk/, e a aplicação segue exatamente a versão do harness — a build atual é 0.1.7-rc.2.

O que aquele host estava servindo em 25 de setembro de 2026:

• Windows — deepseek-harness-0.1.7-rc.2-win-x64.exe, um instalador de 288 MB, com um arquivo .blockmap ao lado dele para atualizações delta.

• macOS — deepseek-harness-0.1.7-rc.2-mac-arm64.dmg, uma imagem de disco de 368 MB, ou a mesma compilação como um .zip de 373 MB. Somente Apple silicon.

• Versão — 0.1.7-rc.2, com lançamento em 24 de setembro de 2026, correspondendo à versão do harness na tag next do npm.

• Ausente — nenhum build para Intel-Mac (o feed de atualização mac-x64 retorna 404) e nenhum alvo Linux de qualquer tipo.

Cada alvo também publica um feed de atualização em download.deepseek.com/dsh-desk/feeds/, cujo campo releaseDate é a data de compilação. Verificar esse arquivo é a forma mais rápida de ver se existe uma compilação mais recente sem esperar que o aplicativo ofereça uma.

Por que o cliente oficial é diferente dos wrappers da comunidade. Ele é first-party e se atualiza automaticamente, traz o runtime no instalador em vez de baixá-lo na primeira inicialização, e não serve a interface a partir da porta 3080 do perfil web: o shell carrega o aplicativo por meio de um esquema interno dsh-app:// e conversa com um processo host privado em sua própria porta, 19387 por padrão. Ele também se comporta como um aplicativo de desktop — fechar a janela mantém tarefas em execução vivas (o Windows mantém um ícone na bandeja do sistema), ao sair ele pergunta primeiro quando há trabalho em andamento, e as notas de versão 0.1.7-rc.2 adicionam um onboarding de primeira execução que apresenta o crédito disponível e separa tarefas financiadas pela conta de tarefas com chave de API, para que você possa entrar com uma conta Deep​Seek em vez de colar uma chave.

Duas ressalvas, porque este cliente foi distribuído discretamente, em vez de anunciado. O README do repositório ainda documenta apenas o npx e a compilação a partir do código-fonte, e a página do projeto em www.deepseek.com/harness não traz nenhum link de download — os binários e o feed de atualizações deles estão ativos no próprio host da DeepSeek, que foi o que verificamos em 25 de setembro de 2026, mas nenhuma nota de lançamento em lugar algum os descreve. E não executamos os instaladores, então este guia não toma posição sobre o estado de assinatura ou notarização dos binários publicados; o pipeline de empacotamento no repositório de fato inclui etapas de assinatura de código do Windows e de notarização da Apple, e isso é tudo o que se pode dizer de fora.

Uma consequência de o build de desktop acompanhar a versão do harness: atualmente ele está à frente de uma instalação padrão de linha de comando. A tag latest do npm ainda aponta para 0.1.5-rc.3, enquanto todo artefato de desktop está em 0.1.7-rc.2. Se você quiser o harness mais recente em uma plataforma que o aplicativo de desktop não cobre, instale a tag explicitamente — npx @deepseek-ai/dsh@next web — em vez de confiar no padrão.

Método 2 — o one-liner npx (todas as plataformas, incluindo Linux)

O início rápido oficial é um único comando, e é genuinamente um único comando:

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (npm's latest tag currently resolves to 0.1.5-rc.3, not the newest harness), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

A primeira inicialização tem exatamente duas etapas de configuração:

• Adicione uma chave de modelo. Configurações → Modelos → insira sua chave de API. Ela é armazenada em $DSH_HOME/.credentials.yaml e não é mostrada em texto simples depois. Em uma instalação padrão DSH_HOME tem como padrão ~/.dsh.

• Escolha um espaço de trabalho. Adicione o diretório do projeto no qual o dsh pode trabalhar. A entrada permanece bloqueada até que ambas as etapas sejam concluídas.

Então envie uma primeira tarefa — um bom teste de fumaça é "Resuma este repositório e identifique seus principais pacotes." Se o resumo voltar e as chamadas de ferramenta aparecerem no rastreamento da execução, sua instalação funciona.

Método 3 — compilar a partir do código-fonte

Prefere executar a partir do repositório? O caminho oficial é:

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

Você precisa de pnpm para isso (os contribuidores fixam o pnpm na versão 11.7.0). Escolha a build de origem quando quiser executar a versão mais recente do main em vez do candidato a release publicado, quando você planeja ler ou modificar o harness, ou quando você quer construir um preset personalizado a partir do diretório apps/cli/config/agent-presets/ do repositório. Para todos os demais, o caminho via npx é o mesmo software com menos cerimônia — a build de origem não desbloqueia recursos que o pacote npm não possui.

Os três perfis: web, headless e tui

dsh é fornecido com três perfis de execução, e qual deles você usa depende de onde o trabalho acontece:

• web (padrão) — a interface completa do navegador na porta 3080. É isso que npx @deepseek-ai/dsh web inicia, e é o perfil que a maioria das pessoas instalará primeiro.

• headless — uma tarefa, depois termina. dsh --profile headless "run the test suite and report failures" inicia uma sessão, executa a tarefa, grava os resultados e encerra. O runtime headless é explicitamente um processo de tarefa única: você não pode injetar instruções adicionais durante a execução, e correções são uma nova execução no mesmo workspace. Este é o perfil para integrar em scripts e CI.

• tui — uma interface de terminal para sessões controladas pelo teclado: dsh --profile tui.

Os três compartilham a mesma configuração (~/.dsh/profiles/<name>/) e o mesmo sistema de plugins, portanto mover uma tarefa da interface web para headless é uma troca de comando, não uma reinstalação.

Adicionando plugins

O gerenciamento de plugins é um comando CLI de primeira classe, não uma questão de edição no local:

npx @deepseek-ai/dsh plugin --profile web add <source>

A origem pode ser um nome de pacote npm, um repositório GitHub (github:user/repo), um tarball ou uma pasta local. A primeira instalação mais útil é o mercado oficial de plugins, que transforma a descoberta de plugins em uma interface:

npx @deepseek-ai/dsh plugin --profile web add dshmarket

Em seguida, reinicie o serviço web e abra Configurações → Plugin Market para navegar pelo catálogo e instalar com um clique. Duas regras que confundem as pessoas: os pacotes de plugins são montados na inicialização do perfil, então um plugin recém-adicionado precisa de uma reinicialização do dsh web; e um simples npm install não registra um plugin em um perfil — você deve usar dsh plugin. O ecossistema é jovem, mas não vazio: a lista awesome-dsh-plugin mantida pela comunidade já cataloga centenas de plugins em categorias como UI, habilidades, ferramentas, provedores e notificações.

MCP, as quatro predefinições e a reprodução de trajetória

Três recursos importam depois que você supera uma instalação básica:

MCP. dsh fala o Model Context Protocol por meio de um plugin integrado @deepseek-ai/dsh-mcp-client. Hoje isso é configurado em arquivos, não na interface: você edita ~/.dsh/profiles/web/cordis.patch.yml (ou um patch local do projeto) e declara o transporte de cada servidor — stdio para comandos locais como npx @playwright/mcp@latest, streamable-http para URLs remotas. Funciona, mas é a superfície menos polida na prévia; espere instabilidade ocasional e nenhuma GUI para ativar/desativar servidores.

Predefinições. dsh carrega uma de quatro predefinições de agente por sessão, e cada uma é um trade-off diferente:

• Standard — o conjunto completo de ferramentas: edição de arquivos, shell, recuperação de arquivos e da web, habilidades, planejamento, subagentes e fluxos de trabalho. O padrão do dia a dia.

• PTC (Chamada Programática de Ferramentas) — Standard mais um SDK Code Mode que permite ao modelo escrever programas TypeScript para orquestrar chamadas de ferramentas em múltiplas rodadas. Mais poderoso, mais efeitos colaterais.

• Mínimo — apenas bash e um editor de arquivos, nada mais. Feito para benchmark de modelos e reprodução mínima; o modo que a documentação da API DeepSeek V4 Flash referenciou quando divulgaram suas próprias pontuações de agente rodava em "Deep​Seek Harness minimal mode."

• Criação — um playground em tempo de execução: inspecione e carregue plugins Cordis na memória, experimente e consolide uma combinação funcional em um novo preset.

Replay de trajetória.Cada execução grava um log de sessão somente de acréscimo — prompts do sistema, raciocínio, chamadas de ferramentas e seus resultados, agendamento de subagentes. A visualização Trajectory permite inspecionar por origem, retomar, bifurcar, pesquisar e reproduzir uma execução. Esse é o depurador para o trabalho de agentes: quando uma tarefa falha, você não executa novamente e espera; você reproduz a trajetória com falha, bifurca no passo incorreto e testa uma correção sem descartar o original.

A opção do SDK Python

Se você preferir usar o harness a partir do Python em vez de um navegador, há um SDK oficial: pip install deepseek-harness-sdk. Ele inclui o runtime dsh (a wheel do pip traz o runtime Node, então não é preciso instalar Node separadamente), e o uso é um gerenciador de contexto: crie uma instância de Deep​SeekHarness, chame run("task"). Ele herda variáveis de ambiente padrão como DEEPSEEK_API_KEY e DEEPSEEK_BASE_URL, portanto trocar de provedor é uma mudança de configuração. O problema: é Python 3.10+ e suporta apenas Linux x64/arm64 e macOS 14+ arm64 — não há wheel nativa para Windows, o que é uma lacuna real se o Windows for seu host. No Windows, opte pela rota do npm.

Apontando o dsh para os modelos que você paga.

O dsh precisa de uma chave de API do modelo e é deliberadamente agnóstico em relação ao provedor: Configurações → Modelos aceita um provedor personalizado com uma URL base compatível com Open​AI (em settings.yaml, isso é api: openai-completions, baseURL e models, que é uma lista). O padrão é a própria API da Deep​Seek; um provedor personalizado é onde um gateway de roteamento se torna útil.

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. The models dsh will actually call are all on it: DeepSeek V4 Flash 0731 (deepseek/deepseek-v4-flash-0731, $0.22 per million input tokens and $0.66 per million output), DeepSeek V4 Pro 0813 (deepseek/deepseek-v4-pro-0813, $0.66/$1.98) and DeepSeek V4.1 Flash (deepseek/deepseek-v4.1-flash, $0.15/$0.60), the model Deep​Seek's own rate card bills as deepseek-flash. Every rate doubles inside Deep​Seek's peak windows, 01:00-04:00 and 06:00-10:00 UTC on weekdays; the router passes that surcharge through rather than hiding it, and automatic failover moves a request to another provider if one wobbles. Figures checked against both rate cards on September 25, 2026. For dsh, the practical win is that you can keep the cheap tier for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

Para deixar claro os limites: o OrcaRouter hospeda os modelos que o dsh chama; ele não hospeda o próprio dsh, e também não distribui o cliente desktop — isso vem do próprio host de download da Deep​Seek. O dsh é um runtime de agente local, e você o executa na sua própria máquina.

Onde este guia falha para você — problemas honestos com a prévia

Um tutorial de instalação que apenas informa o que digitar está fazendo metade do trabalho. Aqui está o que a prévia erra hoje, para que você não descubra isso às 2 da manhã:

• Mudanças que quebram compatibilidade são uma promessa, não um aviso. Você está em um release candidate — 0.1.5-rc.3 se usou o padrão do npm, 0.1.7-rc.2 se instalou o aplicativo de desktop ou a tag next. Chaves de configuração, a API de plugins e os formatos de preset podem todos mudar sem aviso. Trate ~/.dsh como estado descartável — o custo de uma atualização ruim é uma reinstalação, e isso é aceitável nesta fase só porque toda rota de instalação aqui é um download ou um único comando.

• Você não precisa do dsh para usar os modelos Deep​Seek como agente. Se seu único objetivo hoje é o DeepSeek V4 Flash ou o DeepSeek V4 Pro em um agente, o endpoint compatível com Anthro​pic da Deep​Seek já funciona no Claude Code e em outras ferramentas de agente sem nenhum software novo. dsh é uma opção oficial, não um pré-requisito. Pule esta instalação até que você queira especificamente o harness nativo.

• O MCP é configurado por arquivos e, ocasionalmente, instável. Sem GUI, sem opção de iniciar/parar por servidor, e relatos práticos descrevem falhas intermitentes. Reserve tempo para depurar YAML se o seu fluxo de trabalho depender de servidores MCP.

• A confiança em plugins é uma decisão de segurança. Plugins de terceiros são executados dentro do processo principal do harness, e não há verificação de assinatura ou de origem no momento da instalação. Instale apenas plugins que você leu ou que venham de uma fonte em que confie, e teste-os em um espaço de trabalho descartável antes de usá-los em trabalho real. O danger-full-access, um perfil de sandbox, pode modificar qualquer arquivo visível — restrinja-o a checkouts descartáveis.

• Existem bugs conhecidos na prévia. Um loop bash travado é um modo de falha documentado (interrompa e tente novamente), e o comportamento em sessões de longa duração ainda está sendo estabilizado.

• As builds de desktop não oficiais não têm mais razão para existir. Até 24 de setembro de 2026, os únicos aplicativos de desktop dsh instaláveis com um clique eram wrappers comunitários não assinados, e a escolha era entre eles e a linha de comando. O cliente oficial elimina o dilema: do próprio fabricante, com runtime incluído, com atualização automática. Não existe um caminho real de migração entre os dois tipos de shell — eles encapsulam o mesmo harness —, então desinstale um e instale o outro e mantenha o mesmo diretório de workspace.

• Se você precisa de estabilidade em produção, aguarde uma versão não-rc. O harness é poderoso, mas ainda imaturo. Para uma stack de agentes em produção, um harness maduro e testado em batalha — ou a rota de endpoint compatível com a Anthro​pic — é a escolha defensável até que o dsh alcance uma tag estável.

Conclusão

A instalação do DeepSeek Harness agora envolve duas tarefas diferentes, dependendo da sua plataforma. No Windows ou em um Mac com Apple silicon, baixe a versão 0.1.7-rc.2 do host próprio da DeepSeek e pronto — sem Node.js, sem terminal e com a versão mais recente do harness em qualquer canal. Em todos os outros lugares, ainda é um único comando no Node 22.19+: npx @deepseek-ai/dsh@next web, depois adicione uma chave de modelo e um workspace e envie uma tarefa de teste. Use headless para scripts, o build do código-fonte apenas se você quiser modificar ou acompanhar a main, e trate o MCP como um trabalho em andamento. A ressalva honesta não mudou: cada um desses canais é uma versão candidata 0.x e vai quebrar coisas no caminho até a estabilidade — uma troca válida se você quiser ver aonde a DeepSeek está levando a camada de agentes. Os modelos que ele executa — DeepSeek V4 Flash 0731, DeepSeek V4 Pro 0813 e DeepSeek V4.1 Flash — estão disponíveis hoje pelo preço de tabela via OrcaRouter, prontos para alimentar o harness do outro lado da instalação.